Webhooks — Eventos em Tempo Real
Receba notificações instantâneas sobre eventos importantes da sua conta. Webhooks permitem que você reaja automaticamente a mudanças sem fazer polling constante.
Recursos Principais
Entrega em Tempo Real
Webhooks são entregues instantaneamente quando um evento ocorre, permitindo que você reaja imediatamente
Segurança Verificada
Cada webhook é assinado com HMAC-SHA256 para garantir que vem realmente da Yup Chat
Retry Automático
Se seu servidor não responder, tentaremos novamente com backoff exponencial até 24 horas
Eventos Estruturados
Payloads JSON bem estruturados com informações completas sobre cada evento
Múltiplos Canais
Receba eventos de SMS, WhatsApp, RCS, Email, Voice e outros canais
Rastreamento
Acompanhe o status de todos os webhooks enviados no painel de controle
Eventos Disponíveis por Canal
SMS
RCS
Voice
Comece Rápido
Configurar Endpoint
Crie um endpoint HTTPS que receberá os webhooks. Seu servidor deve responder com status 2xx dentro de 30 segundos.
POST /webhooks/yup HTTP/1.1
Host: seu-servidor.com
Content-Type: application/json
X-Webhook-Signature: sha256=...
X-Webhook-Timestamp: 1705578600
{
"event": "sms.delivered",
"timestamp": "2024-01-18T10:30:00Z",
"data": { ... }
}Validar Assinatura
Valide a assinatura HMAC-SHA256 de cada webhook para garantir que vem da Yup Chat.
import crypto from 'crypto';
const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
const payload = JSON.stringify(req.body);
const message = `${timestamp}.${payload}`;
const expectedSignature = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(message)
.digest('hex');
if (signature !== expectedSignature) {
return res.status(401).json({ error: 'Invalid signature' });
}Processar Eventos
Processe os eventos recebidos e execute as ações necessárias para sua aplicação.
app.post('/webhooks/yup', async (req, res) => {
const { event, data } = req.body;
switch (event) {
case 'sms.delivered':
await updateMessageStatus(data.message_id, 'delivered');
break;
case 'whatsapp.message.received':
await handleIncomingMessage(data);
break;
case 'call.terminated':
await saveCallRecording(data);
break;
}
res.status(200).json({ success: true });
});Lógica de Repetição
A Yup Chat tenta reenviar webhooks com backoff exponencial se seu servidor não responder com sucesso (2xx). Seu servidor deve responder com um código de status 2xx (200-299) dentro de 30 segundos para confirmar o recebimento.
| Tentativa | Intervalo | Tempo Total |
|---|---|---|
| 1ª | Imediato | 0s |
| 2ª | 5 minutos | 5 min |
| 3ª | 30 minutos | 35 min |
| 4ª | 2 horas | 2h 35min |
| 5ª | 12 horas | 14h 35min |
Melhores Práticas
Faça
- ✓Validar assinatura de cada webhook
- ✓Responder com 2xx dentro de 30 segundos
- ✓Processar webhooks de forma idempotente
- ✓Usar message_id para deduplicação
- ✓Registrar todos os webhooks recebidos
Não Faça
- ✗Ignorar webhooks duplicados
- ✗Fazer operações longas no handler
- ✗Confiar apenas em webhooks (use polling como backup)
- ✗Expor secret do webhook publicamente
- ✗Responder com erro 5xx desnecessariamente
Casos de Uso
Rastreamento de Mensagens
Acompanhe status de entrega, leitura e interação em tempo real
Notificações Automáticas
Notifique usuários sobre eventos importantes sem polling
Integração com CRM
Sincronize dados de chamadas e mensagens com seu CRM
Análise em Tempo Real
Processe eventos para gerar insights e relatórios
Automação de Workflows
Dispare ações automáticas baseadas em eventos
Auditoria e Compliance
Registre todos os eventos para auditoria e conformidade
Pronto para Integrar Webhooks?
Configure seus endpoints de webhook no painel de controle e comece a receber notificações em tempo real.