Eventos dos Webhooks

Na API você pergunta; no webhook a Notifique avisa. Ideal para marcar pedido como entregue ou processar resposta do cliente sem polling.

Em poucas palavras

Toda entrega é um POST application/json para a URL cadastrada.
Eventos sms.* são só SMS, WhatsApp usa message.*.
instanceId vem vazio (SMS não usa instância).
Ative só os eventos que sua integração usa.
Responda 2xx rápido; processamento pesado vai para fila no seu lado.

Configuração geral: Webhooks. Segurança (assinatura HMAC): Segurança de webhooks.

Como vem o POST

{
  "event": "sms.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "smsId": "clxx456...",
    "to": "5511999999999",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

Campo	Descrição
`event`	Nome do evento (ex.: `sms.delivered`)
`workspaceId`	ID do workspace
`instanceId`	Sempre vazio no SMS
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos do envio ou MO (`smsId`, `to`, `status`, etc.)

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id, X-Webhook-Event.

O que seu servidor deve responder

Resposta	Efeito
2xx em até ~10s	Evento entregue; sai da fila
4xx / 5xx / timeout	Retentativa automática (5 min, 30 min, 2 h)

Processamento demorado? Responda 200 logo e processe em background. Acima de ~10 s conta como timeout e o evento pode ser reenviado.

Valide X-Notifique-Signature e timestamp recente. Detalhes: Segurança de webhooks.

Referência por evento

Use estes eventos ao integrar ERP, e-commerce ou automação com SMS.

Envio e status

Evento	Quando dispara	O que fazer com isso
`sms.sent`	Operadora aceitou o SMS	Marcar como enviado
`sms.delivered`	Confirmado entregue (DLR)	Confirmar entrega, cobrança
`sms.clicked`	Clique em link curto do SMS	Campanha / conversão
`sms.failed`	Falha no envio ou DLR de erro	Retentar ou alertar
`sms.cancelled`	Agendamento cancelado	Atualizar pedido

Mensagens que chegam (MO)

Evento	Quando dispara	O que fazer com isso
`sms.received`	Cliente mandou SMS para seu número	Keyword, opt-in, suporte
`sms.replied`	Resposta ligada a um envio seu	Confirmação “SIM/NÃO”, enquete

MO respeita inbound em Settings → Received messages, igual aos outros canais. Guia: Mensagens recebidas e respostas.

Payload de cada evento

Corpo completo do POST. O envelope (event, ids, timestamp) segue o exemplo acima; abaixo, o que muda em data.

sms.sent

{
  "event": "sms.sent",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:29:00.000Z",
  "data": {
    "smsId": "clxx456...",
    "to": "5511999999999",
    "status": "SENT",
    "sentAt": "2025-02-10T14:29:00.000Z",
    "externalId": "ext-abc123",
    "provider": "zenvia"
  }
}

sms.delivered

{
  "event": "sms.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "smsId": "clxx456...",
    "to": "5511999999999",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

sms.failed

{
  "event": "sms.failed",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:29:30.000Z",
  "data": {
    "smsId": "clxx456...",
    "to": "5511999999999",
    "status": "FAILED",
    "failedAt": "2025-02-10T14:29:30.000Z",
    "errorMessage": "invalid_number"
  }
}

sms.cancelled

{
  "event": "sms.cancelled",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T12:00:00.000Z",
  "data": {
    "smsId": "clxx456...",
    "to": "5511999999999",
    "status": "CANCELLED"
  }
}

sms.clicked

Disparado no primeiro clique em link curto rastreado deste SMS.

{
  "event": "sms.clicked",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:35:00.000Z",
  "data": {
    "smsId": "clxx456...",
    "to": "5511999999999",
    "status": "CLICKED",
    "clickedAt": "2025-02-10T14:35:00.000Z"
  }
}

sms.received

{
  "event": "sms.received",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T15:00:00.000Z",
  "data": {
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "bodyPreview": "SIM",
    "receivedAt": "2025-02-10T15:00:00.000Z"
  }
}

sms.replied

Quando o MO está ligado a um envio seu (ex.: resposta a enquete).

{
  "event": "sms.replied",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T15:00:00.000Z",
  "data": {
    "smsId": "clxx456...",
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "replyText": "SIM",
    "status": "REPLIED"
  }
}

Próximos passos

Quick Start: primeiro envio
Introdução: ciclo de status
Escopos: permissões da chave
Webhooks (guia geral)

​Em poucas palavras

​Como vem o POST

​O que seu servidor deve responder

​Referência por evento

​Envio e status

​Mensagens que chegam (MO)

​Payload de cada evento

​Próximos passos

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Referência por evento

Envio e status

Mensagens que chegam (MO)

Payload de cada evento

Próximos passos