Webhooks
Configure webhooks para receber notificações em tempo real sobre status de entrega e respostas dos destinatários.
Webhooks permitem: Rastreamento em tempo real • Atualizações automáticas • Captura de respostas • Auditoria completa
Configuração
Para receber webhooks, configure uma URL pública que aceite requisições POST:
1. Defina o Callback URL no Envio
{
"to": "5511999999999",
"message": "Sua mensagem aqui",
"type": "SMS",
"callbackUrl": "https://sua-aplicacao.com/webhook/nexus"
}
2. Requisitos do Endpoint
- Deve ser acessível publicamente via HTTPS
- Responder com status 200-299 em até 5 segundos
- Processar requisições POST com Content-Type: application/json
- Implementar idempotência (mesma notificação pode ser enviada múltiplas vezes)
Status de Entrega (DLR)
Receba atualizações quando o status de uma mensagem mudar:
Payload do Webhook
{
"event": "delivery_status",
"campaignId": "6584b123c2d3e4f5a6b7c999",
"messageId": "msg_abc123",
"phone": "5511999999999",
"status": "DELIVERED",
"timestamp": "2026-01-20T10:30:00.000Z",
"provider": "INFOBIP",
"errorCode": null,
"errorMessage": null
}
Status Possíveis
| Status | Descrição | Final |
|---|---|---|
SENDING |
Mensagem sendo processada | Não |
SENT |
Enviada ao provedor | Não |
DELIVERED |
Entregue ao destinatário | Sim |
READ |
Lida pelo destinatário (RCS/WhatsApp) | Sim |
FAILED |
Falha na entrega | Sim |
CANCELED |
Cancelada pelo usuário | Sim |
Exemplo de Erro
{
"event": "delivery_status",
"campaignId": "6584b123c2d3e4f5a6b7c999",
"messageId": "msg_abc123",
"phone": "5511999999999",
"status": "FAILED",
"timestamp": "2026-01-20T10:30:00.000Z",
"provider": "INFOBIP",
"errorCode": "INVALID_NUMBER",
"errorMessage": "Número inválido ou não existe"
}
Respostas Recebidas (MO)
Capture respostas enviadas pelos destinatários (Mobile Originated):
Payload do Webhook
{
"event": "message_received",
"campaignId": "6584b123c2d3e4f5a6b7c999",
"phone": "5511999999999",
"message": "SIM",
"receivedAt": "2026-01-20T10:35:00.000Z",
"channel": "SMS"
}
Casos de Uso
- Confirmações: "SIM" ou "NÃO" para confirmar agendamentos
- Pesquisas: Coletar feedback com respostas curtas
- Opt-out: Capturar "SAIR" ou "PARE" para descadastrar
- Suporte: Iniciar atendimento baseado em resposta
Segurança
Validação de Origem
Para garantir que webhooks vêm da Nexus, valide o IP de origem:
IPs Autorizados: Solicite a lista completa de IPs permitidos ao seu gerente de conta e configure whitelist no seu firewall/servidor.
Verificação de Assinatura (Futuro)
Em breve: Validação via HMAC SHA-256 signature no header X-Nexus-Signature
Implementação Segura (Node.js)
app.post('/webhook/nexus', (req, res) => {
// Solicite a lista de IPs autorizados ao seu gerente de conta
const allowedIPs = ['IP_FORNECIDO_PELA_NEXUS_1', 'IP_FORNECIDO_PELA_NEXUS_2'];
const clientIP = req.ip || req.connection.remoteAddress;
if (!allowedIPs.includes(clientIP)) {
return res.status(403).send('Forbidden');
}
const { event, campaignId, status, phone } = req.body;
if (event === 'delivery_status') {
console.log(`Mensagem ${campaignId} para ${phone}: ${status}`);
res.status(200).send('OK');
} else if (event === 'message_received') {
console.log(`Resposta recebida de ${phone}: ${req.body.message}`);
res.status(200).send('OK');
} else {
res.status(400).send('Unknown event');
}
});
Testes de Webhook
Ferramentas Recomendadas
- ngrok: Expor localhost para testes (ngrok.com)
- webhook.site: Receber e inspecionar webhooks
- RequestBin: Debug de payloads HTTP
Exemplo com ngrok
# 1. Instale ngrok brew install ngrok # 2. Inicie seu servidor local na porta 3000 node server.js # 3. Exponha via ngrok ngrok http 3000 # 4. Use a URL gerada como callbackUrl https://abc123.ngrok.io/webhook/nexus
Simulando Webhooks Localmente
curl -X POST http://localhost:3000/webhook/nexus \
-H "Content-Type: application/json" \
-d '{
"event": "delivery_status",
"campaignId": "test123",
"phone": "5511999999999",
"status": "DELIVERED",
"timestamp": "2026-01-20T10:30:00.000Z"
}'
Importante: Não use webhooks para lógica crítica de negócio. Sempre consulte a API diretamente quando precisar de dados em tempo real garantidos.