Webhooks - Notifique

Webhook é a campainha do seu servidor: quando algo acontece na Notifique (mensagem enviada, entregue, resposta do cliente…), a gente toca a campainha com um POST JSON na sua URL.

O que é um webhook?

É uma URL HTTPS no seu sistema que recebe avisos automáticos da Notifique. Em vez de ficar perguntando “já entregou?” para a API, você espera o aviso chegar. Pense como notificação push, só que para o seu backend.

Para que serve?

Com webhooks você pode:

Saber na hora quando uma mensagem foi enviada, entregue, lida ou falhou
Automatizar pedidos, CRM, financeiro e bots sem olhar o painel
Processar mensagens que o cliente mandou (WhatsApp, Telegram, SMS)
Monitorar conexão de instâncias (QR, conectado, desconectado)
Rastrear cliques em links curtos e eventos de Forms

Quando usar?

Situação	Usar webhook?
Precisa reagir na hora quando algo muda	Sim
Quer automatizar (bot, ERP, sistema próprio)	Sim
Só consulta o painel de vez em quando	Não precisa

Como configurar

1. Prepare seu endpoint

Crie uma rota HTTPS que aceita POST com JSON e responde 2xx rápido. Exemplo: https://meusite.com/webhooks/notifique Se o processamento for pesado, enfileire do seu lado e responda 200 logo. É como atender a campainha e resolver a visita depois.

2. Cadastre no painel

Abra Developer → Webhooks, crie um webhook e marque os eventos que importam para você. Também dá para cadastrar pela API com escopos webhooks:manage e webhooks:read. Precisa de chave? Veja Chaves de API.

POST https://api.notifique.dev/v1/webhooks
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu webhook",
  "url": "https://api.seudominio.com/receive",
  "events": ["message.sent", "message.delivered", "sms.sent"],
  "instanceIds": [],
  "domainIds": [],
  "pushAppIds": [],
  "headers": {"Authorization": "Bearer teste"}
}

Guarde o secret da resposta. Você usa ele para validar cada POST.

Cabeçalhos HTTP customizados

Você pode enviar até 10 cabeçalhos em headers. Os valores são guardados criptografados e enviados na verificação inicial, nas entregas e nas retentativas.

{
  "headers": {
    "Authorization": "Bearer teste"
  }
}

Nomes podem ter até 128 caracteres e valores até 2.048; não use quebras de linha. Host, Content-Length, Content-Type, Transfer-Encoding, Connection e X-Notifique-* são reservados. Em GET, os nomes aparecem com valores mascarados (por exemplo, Bearer ********). Use PATCH /v1/webhooks/{id} para alterar cabeçalhos; envie {"headers": {}} para remover todos. No PUT, os valores mascarados podem ser reenviados para manter o segredo atual.

Validação da URL ao cadastrar

Ao cadastrar no painel ou via API, a Notifique envia um POST de verificação com corpo JSON na URL antes de aceitar o webhook.

Resposta do seu servidor	Resultado
2xx	URL aceita
401 ou 403	URL aceita — comportamento intencional: o POST chegou ao app; 401/403 indicam falta de autenticação, não URL inválida
5xx	Cadastro rejeitado — erro no servidor
404, 405 e outros	Cadastro rejeitado

Se o endpoint exige autenticação, responda 401 ou 403 na verificação. A verificação também envia headers customizados, X-Notifique-Signature e X-Notifique-Timestamp; nas entregas reais, valide a assinatura.

3. Valide a assinatura

Cada POST traz X-Notifique-Signature e X-Notifique-Timestamp. Calcule HMAC-SHA256 do secret com {timestamp}.{body bruto} e rejeite timestamps fora de 5 minutos. Detalhes na seção Headers e assinatura abaixo.

4. Trate retentativas

Se seu endpoint falhar, tentamos de novo em 5 min, 30 min e 2 h. Responda 2xx rápido.

Sandbox x Produção

Sandbox (sk_test_...): mesmos nomes de evento; o payload traz sandbox: true
Produção (sk_live_...): eventos reais do tráfego

Simule eventos em Developer → Inbox sandbox. Mais em Sandbox, o que é?.

Formato do payload

Todas as requisições são POST com Content-Type: application/json. O corpo segue a estrutura:

{
  "event": "message.sent",
  "workspaceId": "clxx...",
  "instanceId": "clxx...",
  "messageId": "clxx...",
  "timestamp": "2025-02-09T12:00:00.000Z",
  "data": { ... }
}

Campo	Tipo	Descrição
event	string	Nome do evento (ex.: `message.sent`, `sms.delivered`).
workspaceId	string	ID do workspace.
instanceId	string	ID da instância WhatsApp (vazio para SMS, e-mail e push).
messageId	string \| undefined	ID da mensagem no Notifique (quando aplicável); em `short_link.clicked` é o clickEventId (id do registro de clique).
timestamp	string	ISO 8601; use para anti-replay (janela recomendada: 5 min).
data	object	Dados específicos do evento (veja a página de cada canal abaixo).

Headers e assinatura

Header	Descrição
Content-Type	`application/json`
X-Webhook-Event	Nome do evento.
X-Notifique-Timestamp	Timestamp em segundos (Unix) usado na assinatura.
X-Notifique-Signature	Assinatura: `t={timestamp},v1={hash}`.
X-Workspace-Id	ID do workspace.
Cabeçalhos customizados	Os pares definidos em `headers` no cadastro do webhook.

Cálculo HMAC: hash = HMAC-SHA256(secret, timestamp + "." + body) (body = corpo bruto do POST).
Anti-replay: Rejeite requisições com timestamp fora de uma janela (ex.: 5 minutos).

Mensagens recebidas (inbound)

Para processar o que o cliente mandou (WhatsApp, Telegram, SMS):

Marque o evento no webhook
Configure inbound em Configurações → Mensagens recebidas (EN: Settings → Received messages)

O webhook avisa com um resumo. Para baixar mídia (áudio, imagem, documento) no WhatsApp, use o inboundId na API. Guia completo: Mensagens recebidas e respostas.

Boas práticas

HTTPS sempre na URL cadastrada
Responda 2xx rápido e processe em background
Valide a assinatura em todo POST
Marque só os eventos que sua integração consome

Mais detalhes: Segurança e Confiabilidade.

Eventos por canal

Cada canal tem seus próprios eventos. Marque só o que precisa:

Envio, entrega, inbound, instância e chamadas

SMS

Envio, DLR, MO e respostas

Envio, inbound e instância

Instagram

Envio, comentários e inbound

E-mail

Envio, abertura, clique e bounce

Push

Envio, entrega e clique

RCS

Envio, entrega e falha

Voz

Chamadas e gravações

Forms

Inscrição, confirmação e cancelamento

Links curtos

Cliques e conversões

Números de telefone

Ciclo de vida do número contratado

Automações

Ativar, pausar e lifecycle de runs

Templates (Meta)

Aprovação, rejeição e categoria

Evento de reputação do workspace (trust.score_changed): veja Trust Factor.

Próximos passos

Comece aqui: envie sua primeira mensagem
Chaves de API: credenciais para cadastrar webhooks via API

​O que é um webhook?

​Para que serve?

​Quando usar?

​Como configurar

​1. Prepare seu endpoint

​2. Cadastre no painel

​Cabeçalhos HTTP customizados

​Validação da URL ao cadastrar

​3. Valide a assinatura

​4. Trate retentativas

​Sandbox x Produção

​Formato do payload

​Headers e assinatura

​Mensagens recebidas (inbound)

​Boas práticas

​Eventos por canal

WhatsApp

SMS

Telegram

Instagram

E-mail

Push

RCS

Voz

Forms

Links curtos

Números de telefone

Automações

Templates (Meta)

​Próximos passos

O que é um webhook?

Para que serve?

Quando usar?

Como configurar

1. Prepare seu endpoint

2. Cadastre no painel

Cabeçalhos HTTP customizados

Validação da URL ao cadastrar

3. Valide a assinatura

4. Trate retentativas

Sandbox x Produção

Formato do payload

Headers e assinatura

Mensagens recebidas (inbound)

Boas práticas

Eventos por canal

Próximos passos