Passar para o conteúdo principal

Webhooks: receba eventos da Weve em tempo real

Como configurar webhooks para integrar a Weve com sistemas externos e receber notificações quando algo acontece no seu clube.

Webhooks permitem que sua aplicação receba notificações automáticas sempre que algo importante acontece no seu clube — um novo membro entra, alguém conclui um curso, um certificado é emitido, e por aí vai. Em vez de você ficar consultando a API toda hora pra saber o que mudou, a Weve te avisa.

Como funciona

Você cadastra uma URL HTTPS do seu sistema. Quando um evento que você assinou acontece, a Weve envia uma requisição POST com os dados do evento pra essa URL. Pronto — sua aplicação reage.

Criando um webhook

  1. Acesse Configurações → Integrações → Webhooks.

  2. Clique em Novo webhook.

  3. Preencha:

    • Nome: um identificador interno (ex: "Sincronia CRM").

    • URL: o endpoint HTTPS do seu sistema que vai receber os eventos.

    • Eventos: marque um ou mais eventos que você quer receber.

  4. Salve. Pronto — o webhook já fica ativo e o secret de assinatura é gerado automaticamente.

Eventos disponíveis

Membros

  • member.created — novo membro entra no clube

  • member.updated — dados de um membro são atualizados

  • member.deleted — membro é removido

Conteúdo e cursos

  • content.completed — membro conclui um conteúdo

  • content_group.completed — membro conclui um curso ou série

Quizzes e certificados

  • quiz.completed — membro finaliza um quiz

  • certificate.issued — certificado é emitido

Comunidade

  • community_thread.created — nova publicação na comunidade

  • comment.created — novo comentário

Gamificação

  • badge.earned — membro conquista uma badge

Estrutura do payload

Todo evento chega no seu endpoint com esse formato:

{
  "event": "member.created",
  "timestamp": "2026-05-13T14:23:11.000000Z",
  "data": {
    "user_id": "abc123",
    "email": "[email protected]",
    "name": "João Silva",
    "organization_id": "org_xyz"
  },
  "metadata": {
    "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
    "attempt": 1,
    "signature_version": "v1"
  }
}

Os campos dentro de data variam conforme o evento. metadata.attempt indica em qual tentativa de entrega você está (útil pra detectar reentregas).

Validando a assinatura (importante!)

Toda requisição vem com o header X-Webhook-Signature, que é uma assinatura HMAC-SHA256 do payload usando o secret do seu webhook. Sempre valide essa assinatura antes de processar — é como você garante que a requisição veio mesmo da Weve, e não de alguém tentando se passar por nós.

Exemplo em Node.js:

const crypto = require('crypto');

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Exemplo em PHP:

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($expected, $signatureHeader)) {
    http_response_code(401);
    exit('Assinatura inválida');
}

Atenção: use sempre o corpo bruto (raw) da requisição pra calcular a assinatura — não o JSON reserializado. Qualquer alteração de espaçamento ou ordem quebra a validação.

Headers enviados

  • Content-Type: application/json

  • User-Agent: Weve-Webhooks/1.0

  • X-Webhook-Signature: sha256=...

Resposta esperada e retentativas

Seu endpoint deve responder com um status 2xx (idealmente 200 ou 204) o mais rápido possível — recomendamos enfileirar o processamento e responder na hora.

Se sua resposta não for 2xx (ou der timeout), a Weve retenta automaticamente com backoff. Por isso seu endpoint precisa ser idempotente: use o metadata.delivery_id pra detectar reentregas e não processar o mesmo evento duas vezes.

Testando o webhook

Na lista de webhooks, cada item tem uma ação Testar que dispara uma requisição de teste pra sua URL — útil pra confirmar que o endpoint está acessível antes de eventos reais começarem a chegar.

Boas práticas

  • Sempre HTTPS. URLs HTTP não são aceitas.

  • Responda rápido. Se o processamento for pesado, enfileire e responda 200 imediatamente.

  • Seja idempotente. Use o delivery_id pra evitar processar o mesmo evento duas vezes.

  • Valide a assinatura sempre. Não confie em nenhum payload sem checar o X-Webhook-Signature.

  • Guarde o secret em segurança. Trate como senha — nunca exponha no frontend ou em repositórios públicos.

  • Monitore as falhas. A tela do webhook mostra a taxa de sucesso e as últimas entregas — vale checar de tempos em tempos.

Perguntas frequentes

Posso ter mais de um webhook?

Sim. Você pode criar quantos webhooks quiser, cada um com sua URL e seus próprios eventos.

O que acontece se meu endpoint cair?

A Weve retenta a entrega algumas vezes com intervalo crescente. Após o limite de tentativas, a entrega é marcada como falha e você consegue ver o histórico na tela do webhook.

Como pauso um webhook temporariamente?

Edite o webhook e desative o toggle Ativo. Ele para de receber eventos sem precisar excluir.

Posso trocar o secret?

Sim. Na tela do webhook tem a opção de regenerar o secret — depois disso, atualize seu sistema pra usar o novo valor.

Respondeu à sua pergunta?