webhooks de sms
Webhook de status de SMS: saiba o que aconteceu com cada mensagem
O webhook de status de SMS avisa o seu SaaS quando cada mensagem foi entregue, não chegou ou expirou, com um código de erro normalizado que vira regra de produto, no mesmo padrão de evento do WhatsApp e da voz.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Só o status final
Os eventos são sms.delivered, sms.undelivered, sms.failed e sms.expired. Cada mensagem muda de estado uma vez.
Erro normalizado
O errorCode traz valores como INVALID_NUMBER, LANDLINE e NO_COVERAGE, iguais para qualquer rota de envio.
Conta ou campanha
Um webhook de conta recebe todos os envios com retentativa; um webhook por campanha recebe só aquela campanha.
Assinado com HMAC-SHA256
Com secret configurado, X-DAPI-Signature traz o HMAC do corpo bruto nos dois tipos de webhook.
O webhook de status de SMS é o que faz o SMS deixar de ser um disparo cego dentro do seu SaaS. Sem ele, o seu sistema sabe que a mensagem foi aceita e nada mais. Com ele, sabe se o código de verificação chegou, se o lembrete de vencimento caiu num número fixo, se o comunicado expirou antes de ser entregue. Na D-API, o webhook de status de SMS entrega o resultado final de cada mensagem, com um código de erro normalizado e o mesmo envelope que você já trata nos eventos de voz.
Esta página explica os dois tipos de webhook, os eventos, os códigos de erro e o código de um endpoint seguro. Os endpoints que geram esses eventos estão no hub de API de SMS.
Dois webhooks com garantias diferentes
O SMS tem dois canais de webhook independentes, que podem ser usados juntos.
| Webhook de conta | Webhook por campanha | |
|---|---|---|
| Onde configura | Uma vez, no painel, canal sms |
Na campanha de disparo em massa |
| O que recebe | Todos os envios: API avulsa, em massa e fluxos | Só os destinatários daquela campanha |
| Formato | Envelope com data |
Campos no nível raiz, com campaignId e recipientId |
| Entrega | Fila durável, retentativas, circuit breaker, logs | Uma chamada HTTP, sem retentativa |
| Header de canal | X-DAPI-Webhook-Channel: sms |
Não envia; aceita headers personalizados |
Para um SaaS, o webhook de conta é a fonte da verdade: ele recebe tudo que sai por /sms/send e /sms/bulk e não perde evento quando o seu endpoint oscila. O webhook por campanha serve para casos pontuais, como mandar o status de uma campanha específica direto para o sistema de um cliente do seu SaaS.
Os eventos e o status resultante
| Evento | Quando dispara | status |
|---|---|---|
sms.delivered |
A mensagem foi entregue ao destinatário | delivered |
sms.undelivered |
A operadora reportou que não foi entregue | undelivered |
sms.failed |
Falha de rede depois do aceite | undelivered |
sms.expired |
A mensagem expirou antes da entrega | expired |
No webhook de conta, o data traz messageId, to em E.164, status, errorCode, segments e timestamp:
{
"event": "sms.undelivered",
"channel": "sms",
"data": {
"messageId": "a1b2c3d4-...",
"to": "+5511999999999",
"status": "undelivered",
"errorCode": "LANDLINE",
"segments": 1,
"timestamp": "2026-01-24T23:00:00.000Z"
},
"timestamp": "2026-01-24T23:00:00.000Z"
}
O messageId é o mesmo devolvido por /sms/send e em cada item de results do /sms/bulk. O status de uma mensagem só avança de “enviada” para um estado final e nunca volta, então o seu modelo de dados precisa de uma única transição por mensagem.
Códigos de erro que viram regra de produto
O errorCode vem normalizado e é null nos eventos de entrega e de expiração. A tabela abaixo agrupa os valores pelo que o seu produto deve fazer:
errorCode |
Significado | Ação sugerida |
|---|---|---|
INVALID_NUMBER |
Número de destino inválido | Marcar o contato para revisão |
LANDLINE |
Telefone fixo, não recebe SMS | Trocar para voz ou pedir celular |
BLACKLIST |
Número em lista de bloqueio | Remover das próximas campanhas |
CANCELED |
Envio cancelado | Registrar e não reenviar |
NO_WHATSAPP |
Destino sem WhatsApp | Registrar para a escolha de canal |
CONTENT_BLOCKED |
Conteúdo bloqueado | Mostrar ao cliente para revisar o texto |
REJECTED |
Rejeitada pela operadora | Revisar texto e remetente |
NETWORK_ERROR |
Erro de rede até a operadora | Tentar de novo ou usar outro canal |
NO_COVERAGE |
Sem cobertura para o destino | Usar outro canal |
NOT_RECEIVED |
O destino não recebeu | Usar outro canal |
Num software de cobrança, por exemplo, LANDLINE pode disparar automaticamente uma ligação de URA com o mesmo aviso, enquanto INVALID_NUMBER abre uma tarefa de atualização cadastral para o time do seu cliente.
Um endpoint seguro para os dois formatos
Os dois webhooks enviam X-DAPI-Signature com o HMAC-SHA256 em hexadecimal do corpo bruto quando há secret configurado. Calcule sobre o corpo recebido, sem re-serializar o JSON, e compare em tempo constante. Se o seu SaaS usa os dois tipos, um normalizador simples resolve a diferença de envelope:
import crypto from "node:crypto";
type StatusSms = {
event: string;
messageId?: string;
campaignId?: string;
recipientId?: string;
to: string;
status: string;
errorCode: string | null;
segments: number;
timestamp: string;
};
export function assinaturaValida(rawBody: Buffer, header: string | undefined, secret: string) {
const esperado = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const recebido = header ?? "";
return recebido.length === esperado.length &&
crypto.timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado));
}
export function normalizar(body: any): StatusSms {
return body.data ? { event: body.event, ...body.data } : body;
}
Depois de validar, responda 2xx rápido e processe numa fila sua. Como o webhook de conta repete entregas que falharam, use event mais messageId (ou recipientId, no de campanha) como chave de idempotência.
Modelando o status num SaaS multi-tenant
O webhook de conta concentra os eventos de todos os clientes do seu SaaS. No envio, grave o messageId com o tenant e o objeto de negócio (o pedido de código, a fatura, o comunicado). No evento, o lookup por messageId resolve tudo. Alguns usos por segmento:
- Plataforma de e-commerce:
sms.deliveredno código de checkout libera o botão “reenviar” só depois de um tempo;sms.undeliveredoferece o código por WhatsApp na hora. O fluxo inteiro está em SMS de código de verificação. - Software de clínicas: o relatório da campanha de lembretes mostra entregues, fixos e inválidos, e o cliente corrige o cadastro dos pacientes a partir dele.
- Gestão de academias: o
segmentsde cada evento soma o consumo do mês por unidade, para o seu SaaS repassar o custo certo.
O envelope com event, channel, data e timestamp é o mesmo dos eventos de voz, então o roteador de webhooks do seu backend trata os dois canais com o mesmo código de assinatura. A lista completa de eventos e códigos está na documentação da D-API, e o artigo API de SMS para SaaS mostra como esses eventos alimentam o fallback entre canais.
Time D-API. Atualizado em .
Perguntas frequentes
Por que não recebo o evento sms.sent?
Porque o aceite e a cobrança acontecem no momento do envio, e a própria resposta da API já confirma isso com status sent. O webhook notifica só o status final: entregue, não entregue, falha ou expirado.
O webhook de SMS avisa quando alguém responde a mensagem?
Não. O SMS da D-API é só de saída e não existe evento de SMS recebido. Para conversa de mão dupla, use o WhatsApp na mesma conta, que tem webhook de mensagens recebidas.
Qual a diferença entre sms.failed e sms.undelivered?
Os dois resultam no status undelivered. O sms.undelivered indica que a operadora reportou a não entrega; o sms.failed indica uma falha de rede depois do aceite do envio.
O webhook por campanha tem retentativa?
Não. Ele é entregue numa única chamada HTTP e, se o seu endpoint estiver fora do ar naquele momento, o evento não é reenviado. Para entrega confiável, use o webhook de conta como fonte da verdade.
Onde configuro o webhook de SMS?
O webhook de conta é configurado uma vez no painel da D-API, no canal sms, com URL e secret. O webhook por campanha é configurado na própria campanha de disparo em massa, também no painel.