Como enviar eventos do WhatsApp para seu servidor com webhooks

Webhooks de saída deixam o WACRM enviar um evento do WhatsApp para uma URL que você controla, assinado para que você possa confirmar que ele realmente veio do WACRM, em vez do seu servidor ficar consultando a API para ver o que mudou. Este guia cobre os dois lugares que administram os mesmos endpoints de webhook — a tela Settings → Apps & Connectors → Webhooks do Workspace e a Core API diretamente — e diz com clareza quais eventos, tentativas e limites existem hoje.

O que você precisa antes de começar

• Uma conta WACRM Workspace com pelo menos um projeto, no plano Advanced ou superior (com acesso de proprietário, para administrar webhooks pelo Workspace).
• Um servidor que você controla, capaz de receber uma requisição POST por HTTPS e responder com um status 2xx.
• Só para os passos da API: curl (ou qualquer cliente HTTP que consiga definir um cabeçalho), e uma API key com os scopes wa_webhooks:read/wa_webhooks:write em Developer / API & MCP.

Adicione um endpoint de webhook no Workspace

1. Abra Settings → Apps & Connectors → Webhooks. Esta tela é só para o proprietário — um membro da equipe sem acesso de proprietário não vai ver nenhuma forma de adicionar ou mudar um endpoint aqui.
2. Clique em Add endpoint.
3. Digite a Endpoint URL do seu servidor — ela precisa começar com https://, e é recusada se resolver para um endereço privado, loopback, link-local ou outro endereço reservado (isso é checado de novo no momento da entrega, então um hostname que muda de destino depois de criado também é pego).
4. Marque os Events to send que você quiser: message.inbound (chegou uma mensagem do WhatsApp) e/ou message.status (mudou o status de entrega de uma mensagem). São os únicos dois eventos disponíveis hoje.
5. Clique em Create endpoint.

Um diálogo Your new webhook signing secret abre na hora, logo após a criação, mostrando o segredo exatamente uma vez — copie agora. O WACRM nunca guarda nem registra uma cópia legível dele, e não consegue mostrar esse mesmo segredo de novo; se você perdê-lo, rotacione por um novo (veja abaixo).

Verifique a assinatura no seu servidor

Cada entrega — um evento real, um reenvio ou um envio de teste — carrega um cabeçalho X-WACRM-Signature no formato t=<timestamp unix>,v1=<HMAC-SHA256 em hex de "<t>.<corpo bruto>", assinado com o segredo do seu endpoint>. Recalcule o mesmo HMAC sobre o corpo exato da requisição e compare com v1 antes de confiar no payload; nunca confie só no corpo. É o mesmo padrão de webhook assinado que a maioria dos provedores de webhook usa (veja as fontes de HMAC e webhooks abaixo) — com placeholders no lugar do seu segredo real, nunca um verdadeiro:

const crypto = require('crypto');

// header: o valor bruto de X-WACRM-Signature; rawBody: os bytes exatos que o WACRM enviou,
// não um JSON.parse(body) reserializado — diferenças de espaço quebram o HMAC.
function isValidWebhookSignature(header, rawBody, endpointSecret) {
  const [tPart, v1Part] = header.split(',');
  const timestamp = tPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', endpointSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return v1Part === `v1=${expected}`;
}

Envie um teste, veja Deliveries e reenvie uma que falhou

1. Na linha do endpoint, clique em Send test. Isso envia exatamente um evento webhook.test assinado pelo mesmo caminho de entrega, a mesma checagem de SSRF e a mesma assinatura de um evento real — útil para confirmar que seu servidor valida a assinatura corretamente antes de ligar o tráfego real. Tem um limite de 5 envios de teste por endpoint por minuto; um sexto dentro do mesmo minuto é rejeitado.
2. Clique em Deliveries para abrir a lista de tudo que foi enviado para esse endpoint — evento, status, status HTTP, tentativas e a hora da última tentativa, do mais recente para o mais antigo. As entregas ficam guardadas por 30 dias e depois são removidas.
3. Para uma entrega marcada como Failed, clique em Redeliver. Isso reenvia exatamente o mesmo payload como uma entrega totalmente nova — a linha falha original é mantida como está, então você ainda tem um registro do que aconteceu da primeira vez.

Um endpoint desligado (Active desativado) recusa de cara tanto Send test quanto Redeliver — ligue de novo primeiro.

Rotacione o segredo

Se seu segredo vazar, ou se você simplesmente quiser um novo, clique em Rotate secret na linha do endpoint. O mesmo diálogo de revelação única abre com o segredo novo — copie na hora, porque o segredo antigo para de verificar entregas imediatamente, sem nenhuma janela de sobreposição para assinaturas em trânsito. Atualize seu servidor com o segredo novo antes de rotacionar, ou sua verificação vai começar a falhar no momento em que você confirmar.

Faça o mesmo pela API

Tudo acima também pode ser acessado diretamente, com os scopes wa_webhooks:read/wa_webhooks:write — marque os dois em Restrict what this key can do (advanced) → WhatsApp CRM scopes ao criar uma key em Developer / API & MCP. Nenhum dos dois scopes é concedido por padrão a nenhuma key, porque um endpoint recebe o conteúdo de mensagens real do seu projeto.

curl -s -X POST https://api.wacrm.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_live_your_scoped_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "events": ["message.inbound", "message.status"]}'

{
  "data": {
    "id": "7e9b9b7a-...-endpoint-uuid",
    "url": "https://your-server.com/webhook",
    "events": ["message.inbound", "message.status"],
    "active": true,
    "created_at": "2026-11-08T09:00:00+00:00",
    "secret": "whsec_your_one_time_secret"
  }
}

secret só aparece nessa resposta de criação e numa resposta de rotate-secret — qualquer outra chamada, mesmo buscar o mesmo endpoint de novo, omite isso por completo. Um projeto pode ter no máximo 20 endpoints; criar um 21º responde 409 {"error": {"code": "endpoint_limit_reached"}}. PATCH recebe o campo que você está mudando entre url/events/active (precisa de pelo menos um) e nunca devolve um secret. Um reenvio ou um envio de teste contra um endpoint com active: false responde 409 {"error": {"code": "endpoint_inactive"}} antes de qualquer outra coisa rodar; um sexto envio de teste no mesmo minuto responde 429 {"error": {"code": "rate_limited"}}.

O que funciona hoje e o que ainda não

Pronto para testar isso no seu próprio projeto? Solicite acesso antecipado para conseguir um Workspace, ou veja os preços primeiro se ainda estiver comparando planos. Para mais guias como este, veja a lista completa de guias.