Pular para o conteúdo
D-APITestar grátis

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.delivered no código de checkout libera o botão “reenviar” só depois de um tempo; sms.undelivered oferece 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 segments de 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.