Visão geral dos webhooks

Os webhooks de SMS notificam seu sistema sobre o status de entrega das mensagens enviadas: quando um SMS é entregue, não entregue ou expira. O produto é outbound-only — não há eventos de SMS recebido.

Os dois canais

Há dois canais independentes de webhook, que podem ser usados juntos ou separadamente.

Webhook de conta — todos os envios

Configurado uma vez por conta no painel. Dispara para todos os envios da conta (API avulsa, disparos em massa e fluxos), independente da campanha. Use quando um único endpoint concentra o status de tudo que a conta envia.

Webhook por campanha — apenas aquela campanha

Configurado na própria campanha de disparo em massa. Dispara somente para os destinatários daquela campanha. Use para rotear o status de uma campanha específica a um endpoint dedicado.

O evento sms.sent não é entregue aos webhooks: a cobrança e o aceite acontecem no momento do envio, então só os eventos de status final são notificados. O produto é outbound-only — não existe evento de SMS recebido.

Envelope — webhook de conta

O webhook de conta envia o conteúdo do evento dentro de data, junto de channel e timestamp no nível raiz.

{
  "event": "sms.delivered",
  "channel": "sms",
  "data": {
    "messageId": "a1b2c3d4-...",
    "to": "+5511999999999",
    "status": "delivered",
    "errorCode": null,
    "segments": 1,
    "timestamp": "2026-01-24T23:00:00.000Z"
  },
  "timestamp": "2026-01-24T23:00:00.000Z"
}

event

string

required

Nome do evento (ex: sms.delivered). Veja Eventos.

channel

string

required

Canal de origem. Sempre "sms".

data

object

required

Detalhes da entrega. Veja a página de Eventos para cada campo.

timestamp

string

required

Momento do envio do webhook em ISO 8601 (UTC).

Envelope — webhook por campanha

O webhook por campanha é plano: os campos ficam no nível raiz e ele inclui campaignId e recipientId para correlação.

{
  "event": "sms.delivered",
  "campaignId": "...",
  "recipientId": "...",
  "to": "+5511999999999",
  "status": "delivered",
  "errorCode": null,
  "segments": 1,
  "timestamp": "2026-01-24T23:00:00.000Z"
}

event

string

required

Nome do evento (ex: sms.delivered).

campaignId

string

required

ID da campanha que originou o disparo.

recipientId

string

required

ID do destinatário dentro da campanha.

string

required

Número de destino em formato E.164.

status

string

required

Status resultante da entrega. Veja Eventos.

errorCode

string | null

required

Código de erro normalizado em caso de falha, ou null. Veja a tabela de códigos em Eventos.

segments

number

required

Quantidade de segmentos (partes) do SMS.

timestamp

string

required

Momento do evento em ISO 8601 (UTC).

Headers

Header	Valor	Canal
`Content-Type`	`application/json`	Ambos
`X-DAPI-Webhook-Channel`	`sms`	Apenas webhook de conta
`X-DAPI-Signature`	HMAC-SHA256 (hex) do corpo bruto	Ambos, somente se houver secret

A X-DAPI-Signature só é enviada quando um secret está configurado. Ela é o HMAC-SHA256, em hexadecimal, do corpo bruto (raw body) da requisição.

O header X-DAPI-Webhook-Channel é enviado somente no webhook de conta. O webhook por campanha envia apenas Content-Type (mais os headers personalizados configurados na campanha, se houver) e, quando há secret, a X-DAPI-Signature.

Validando a assinatura

Calcule o HMAC sobre o corpo bruto recebido (não sobre o JSON re-serializado) e compare com o header usando comparação de tempo constante (timing-safe):

const sig = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
// comparar (timing-safe) com o header X-DAPI-Signature

Entrega e confiabilidade

A garantia de entrega difere entre os dois canais.

Webhook de conta — fila durável

Entregue por uma fila durável, com retentativas, circuit breaker por URL e logs de entrega (webhook_logs). Em caso de falha temporária, a entrega é repetida automaticamente.

Webhook por campanha — fire-and-forget

Entregue por uma única chamada HTTP sem retentativa (fire-and-forget). Se o endpoint estiver indisponível no momento, o evento não é reenviado.

Como o webhook por campanha não tem retentativa, garanta que o endpoint responda rapidamente e esteja disponível. Para entrega confiável, prefira o webhook de conta.

Próximos passos

Veja a lista de eventos, o status resultante de cada um e os códigos de erro normalizados em Eventos.

​Os dois canais

​Envelope — webhook de conta

​Envelope — webhook por campanha

​Headers

​Validando a assinatura

​Entrega e confiabilidade

​Próximos passos

Os dois canais

Envelope — webhook de conta

Envelope — webhook por campanha

Headers

Validando a assinatura

Entrega e confiabilidade

Próximos passos