Skip to main content
Com os webhooks de SMS você é notificado em tempo real sobre o ciclo de vida dos seus envios: quando o SMS foi aceito pelo provedor, quando foi entregue ao destinatário ou quando falhou.

​
Estrutura do corpo (payload)

O corpo da requisição segue sempre esta estrutura padrão, facilitando a tipagem no seu backend: 
{
  "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"
  }
}
Nos eventos de SMS, o campo instanceId vem vazio, pois SMS não usa instâncias (diferente do WhatsApp). O identificador do SMS e os dados do evento ficam em data (smsId, to, status, sent_at, delivered_at, failed_at, external_id, provider, etc.). Os campos de identificação (event, workspace_id, timestamp) são constantes.

​
Tabela de Eventos (Escopos)

Ao configurar um Webhook no painel, você escolhe quais eventos deseja ouvir. Para SMS, ative apenas o que for útil para sua aplicação.

​
Eventos de ciclo de vida do SMS

  • sms.sent SMS foi aceito e enviado ao provedor.
  • sms.delivered SMS foi entregue ao destinatário (DLR).
  • sms.failed SMS falhou no envio ou foi reportado como falha.
  • sms.cancelled SMS agendado foi cancelado.

​
SMS recebido (MO)

Quando o provedor de SMS envia um MO (mensagem de entrada) para a Notifique e o registro é persistido:
  • sms.received — todo SMS de entrada armazenado (data inclui inboundId, from, body, provider, relatedSmsId quando houver correlação com um envio).
  • sms.replied — mesmo MO quando está vinculado a um SmsLog de saída (data inclui smsId do envio original).
Configure no painel do seu provedor de SMS a URL de retorno MO indicada na documentação de integração da Notifique. Para MO sem id_sent/refer que casem com um envio, é possível definir no servidor uma variável de ambiente com o ID do workspace padrão — consulte a referência de variáveis de ambiente.

​
Retorno de cada evento (SMS)

Abaixo, o corpo completo (body) que a Notifique envia no POST para cada evento de SMS. O campo data é o que varia; o restante da estrutura é sempre o mesmo. sms.sent 
{
  "event": "sms.sent",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "smsId": "clxxsms123",
    "to": "5511999999999",
    "status": "SENT",
    "sentAt": "2025-02-20T14:00:00.000Z",
    "externalId": "provider-msg-123",
    "provider": "ZENVIO"
  }
}
Campos opcionais em data: externalId, provider. sms.delivered 
{
  "event": "sms.delivered",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:30.000Z",
  "data": {
    "smsId": "clxxsms123",
    "to": "5511999999999",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-20T14:00:30.000Z"
  }
}
Todos os campos em data são enviados (nenhum opcional). sms.failed 
{
  "event": "sms.failed",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "smsId": "clxxsms123",
    "to": "5511999999999",
    "status": "FAILED",
    "failedAt": "2025-02-20T14:00:00.000Z",
    "errorMessage": "Invalid number"
  }
}
Campo opcional em data: errorMessage. sms.received 
{
  "event": "sms.received",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T15:00:00.000Z",
  "data": {
    "inboundId": "clxxinbound123",
    "from": "5511988887777",
    "body": "Sim, confirmo.",
    "provider": "GATEWAY_A",
    "relatedSmsId": "clxxsms123",
    "externalMoId": "987654321",
    "refer": null,
    "status": "received"
  }
}
relatedSmsId pode ser null se o MO não foi correlacionado a um envio. sms.replied 
{
  "event": "sms.replied",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T15:00:00.000Z",
  "data": {
    "inboundId": "clxxinbound123",
    "smsId": "clxxsms123",
    "from": "5511988887777",
    "body": "Sim, confirmo.",
    "provider": "GATEWAY_A",
    "externalMoId": "987654321",
    "refer": null,
    "status": "replied"
  }
}

​
Segurança e Validação (Headers)

Para garantir que o POST veio da Notifique e não de um terceiro, a Notifique envia headers de assinatura em todas as requisições de webhook.
HeaderDescrição
X-Notifique-SignatureHash HMAC-SHA256 do corpo da requisição, assinado com seu Segredo de Webhook. Formato: t=timestamp,v1=hash.
X-Notifique-TimestampMomento exato (Unix Timestamp em segundos) em que o evento foi gerado. Use para evitar Replay Attacks.
X-Workspace-IdID do workspace, para facilitar roteamento em sistemas multi-tenant.
X-Webhook-EventNome do evento (ex.: sms.sent, sms.delivered).
Content-Typeapplication/json.
Dica de segurança: Sempre verifique se o timestamp é recente (ex.: menos de 5 minutos) e recalcule o hash para validar a origem. O cálculo da assinatura é: HMAC-SHA256(secret, timestamp + ”.” + body), onde body é o corpo bruto do POST (string JSON).

​
Respostas esperadas

O seu servidor deve responder à requisição o mais rápido possível para evitar timeouts.
StatusSignificado
2xxSucesso. O evento é marcado como entregue e sai da fila da Notifique.
4xx / 5xx / timeoutFalha. A Notifique agenda retentativas automáticas (ex.: 5 min, 30 min, 2 h; até 4 tentativas).
Importante: Se o seu processamento for demorado (ex.: atualizar um CRM ao receber sms.delivered), responda 200 OK imediatamente e processe a lógica em background (job assíncrono). Se você demorar mais de 10 segundos, a Notifique considerará timeout e reenviará o evento.