Skip to main content

​
O que são webhooks?

Webhooks são notificações HTTP que o envia ao seu servidor quando eventos acontecem — como uma mensagem recebida, status de entrega, ou uma atualização de template. Em vez de o seu sistema consultar a API periodicamente (polling), o envia os eventos para você assim que acontecem.
Webhooks exigem a role ENTERPRISE na sua conta. Se sua conta não tem essa role, as chamadas de CRUD de webhook retornam 422. Entre em contato com o suporte para habilitar.

​
Tipos de webhook

O tem dois tipos de webhook. O que muda entre eles são os eventos aceitos e a forma de associação — cada seção detalha as suas particularidades. O restante desta página vale para os dois tipos.

Webhooks de canal

Recebem os eventos de um canal específico (mensagens, entrega, conexão).

Webhooks de template

Recebem os eventos de template do WhatsApp, independentes de instância.

​
Formatos de payload

O suporta três formatos de payload:
payloadFormat vale apenas para webhooks de canal. Nos webhooks de template o formato é sempre DEFAULT e o campo é descartado.

​
Autenticação do webhook

Você pode configurar como o se autentica ao chamar sua URL:

​
Assinatura HMAC

Para garantir que as requisições recebidas são realmente do e não foram adulteradas, habilite a assinatura HMAC configurando signing: true ao criar o webhook. Quando habilitado:
  • Um secret de 64 caracteres hexadecimais é gerado e retornado apenas uma vez na criação/atualização.
  • Cada requisição enviada ao seu webhook inclui um header com a assinatura HMAC-SHA256 calculada sobre o payload.
  • Você verifica a assinatura no seu servidor usando o secret armazenado.
O secret é exibido apenas na resposta de criação ou de atualização com signing: true. Armazene-o com segurança — ele não pode ser recuperado depois.