Webhooks
Recibe notificaciones en tiempo real cuando ocurren eventos en la plataforma. Ideal para sincronizar datos con tus sistemas.
Configurar un Webhook
- 1Ve a Configuración → Integraciones → Webhooks
- 2Haz clic en "Nuevo Webhook"
- 3Ingresa la URL de destino (debe ser HTTPS)
- 4Selecciona los eventos que quieres recibir
- 5Guarda y copia el Secret para validar firmas
Eventos Disponibles
| Evento | Descripción |
|---|---|
| conversation.created | Nueva conversación iniciada |
| conversation.updated | Conversación actualizada (estado, asignación) |
| conversation.closed | Conversación cerrada |
| message.received | Nuevo mensaje recibido del cliente |
| message.sent | Mensaje enviado por el agente |
| contact.created | Nuevo contacto creado |
| contact.updated | Datos de contacto actualizados |
| agent.escalation | Conversación derivada a humano |
Formato del Payload
Cada webhook envía un POST con el siguiente formato JSON:
JSON Payload
{
"event": "message.received",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"conversationId": "conv_abc123",
"messageId": "msg_xyz789",
"content": "Hola, necesito información",
"contact": {
"id": "contact_123",
"name": "Juan Pérez",
"phone": "+595981234567"
},
"channel": "whatsapp"
}
}Verificar Firma
Cada petición incluye un header X-Arizar-Signaturepara verificar la autenticidad:
Node.js - Verificar firma
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const hash = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');
return hash === signature;
}Política de Reintentos
- Tu endpoint debe responder con código 2xx en menos de 5 segundos
- Reintentos automáticos: 3 intentos con backoff exponencial
- Intervalos: 1 minuto, 5 minutos, 30 minutos
- Después de 3 fallos, el webhook se desactiva temporalmente
Buenas Prácticas
- • Responde rápido (código 200) y procesa de forma asíncrona
- • Implementa idempotencia para manejar posibles duplicados
- • Valida siempre la firma antes de procesar
- • Guarda logs de webhooks recibidos para debugging