Introdução - MemberKit

Como funcionam os webhooks?

Um webhook é uma maneira automática de enviar informações entre sistemas quando certos eventos acontecem. Todos os webhooks usam HTTPS e entregam uma carga JSON que pode ser usada pelo seu sistema. Ao ativar um webhook, ele envia requisições POST para o endereço configurado sempre que o evento ocorrer, com detalhes sobre o que ocorreu. Isso permite que você crie integrações fantásticas. Você pode usar os eventos de webhooks para fazer coisas como:

Disparar um SMS com a senha de acesso para o número de celular do aluno
Alimentar seu CRM com a porcentagem de conclusão do aluno em cada curso
Avisar seus alunos por email sobre novas aulas cadastradas na plataforma

Para conseguir usar os webhooks da MemberKit, você precisa:

Acessar a página Integrações › Disponíveis › Webhooks e depois registrar uma URL de callback que comece com https://. Para testes, recomendamos o uso do Mockbin para receber os webhooks.
Pronto! Agora você receberá os eventos selecionados.

Verificando a assinatura

Cada webhook tem um segredo de assinatura, que começa com whsec_. Ele aparece na página do webhook, em Integrações, e no campo secret da API de webhooks. Não compartilhe o segredo publicamente. As requisições seguem o padrão Standard Webhooks e trazem três cabeçalhos:

Cabeçalho	Descrição
`webhook-id`	Identificador único da notificação. Ele se repete nas retentativas.
`webhook-timestamp`	Momento do envio, em segundos desde 1970 (Unix).
`webhook-signature`	Assinatura no formato `v1,<assinatura>`.

A assinatura é um HMAC-SHA256, codificado em base64, do texto {webhook-id}.{webhook-timestamp}.{corpo}. A chave é o segredo sem o prefixo whsec_, decodificado de base64. Use o corpo exatamente como recebido, antes de convertê-lo em JSON. A forma mais simples de verificar é usar uma das bibliotecas oficiais do Standard Webhooks, disponíveis para JavaScript, Python, PHP, Ruby, Go, Java e outras linguagens:

import { Webhook } from "standardwebhooks"

const webhook = new Webhook(process.env.MEMBERKIT_WEBHOOK_SECRET)
const payload = webhook.verify(body, headers)

Se preferir não usar uma biblioteca, a verificação manual em Node.js fica assim:

import crypto from "node:crypto"

function verify(secret, headers, body) {
  const id = headers["webhook-id"]
  const timestamp = headers["webhook-timestamp"]
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64")
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64")

  return headers["webhook-signature"].split(" ").some((signature) => {
    const [version, value] = signature.split(",")
    return version === "v1" && value.length === expected.length && crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected))
  })
}

Recomendamos também recusar notificações cujo webhook-timestamp esteja a mais de 5 minutos do horário atual, para evitar que uma requisição antiga seja reenviada por terceiros. As bibliotecas oficiais já fazem essa checagem.

Retentativas

A MemberKit tenta enviar cada notificação até 6 vezes, ao longo de cerca de 49 horas, quando não consegue se conectar ao seu sistema ou a conexão expira. Qualquer resposta HTTP, inclusive 4XX e 5XX, conta como entrega e não é reenviada. Se todas as tentativas falharem, o webhook é desativado e precisa ser reativado na página Integrações. Como as retentativas usam o mesmo webhook-id, use esse valor para descartar notificações que você já processou. As notificações podem chegar ao seu servidor em uma ordem diferente da original. Por isso, recomendamos consultar a API quando receber o webhook para garantir que as informações estão atualizadas. É uma boa prática armazenar o conteúdo do webhook antes de processá-lo, pois não é possível reenviá-lo após seu sistema responder com um código HTTP 2XX.

​Como funcionam os webhooks?

​Verificando a assinatura

​Retentativas

Como funcionam os webhooks?

Verificando a assinatura

Retentativas