Webhooks salientes: cómo funcionan
SendApp llama a tu servidor cuando pasa algo en tu cuenta: llega o sale un mensaje, WhatsApp actualiza el estado de un mensaje, una campaña empieza o termina, una plantilla de WhatsApp se aprueba o se rechaza, se reserva una cita. Se configura en Configuraciones → Webhook: hasta 10 direcciones, cada una con su cuenta de IA y sus eventos.
Cada llamada es una petición POST con un cuerpo JSON y las cabeceras
X-SendApp-Event, X-SendApp-Delivery (el id único de la entrega), X-SendApp-Attempt y X-SendApp-Signature.Comprueba la firma:
X-SendApp-Signature vale t=<timestamp>,v1=<HMAC-SHA256 de "timestamp.cuerpo">, calculado con la clave secreta del webhook (Configuraciones → Webhook → Mostrar la clave de firma). Rechaza las peticiones con un timestamp de más de 5 minutos.Responde con un código 2xx en 10 segundos: si no, lo reintentamos tras 1, 5 y 30 minutos. Un código 4xx (salvo 408 y 429) no se reintenta. Tras 20 entregas fallidas seguidas el webhook se desactiva: vuelve a activarlo en Configuraciones → Webhook.
Cada entrega tiene un
delivery_id único, igual en todos los intentos: úsalo para ignorar los duplicados. El orden de llegada no está garantizado: para ordenar los eventos usa occurred_at (y timestamp para los estados).El cuerpo siempre contiene
event, occurred_at, account_ref, training_token (la cuenta de IA) y delivery_id. account_ref identifica tu cuenta y no es una clave: el cuerpo nunca contiene tu clave API. Fotos, audios, vídeos y documentos llegan como enlaces, nunca como archivos.Desde Configuraciones → Webhook puedes enviar una prueba de cada evento: llega con
"test": true. El registro muestra cada entrega con el cuerpo enviado y la respuesta de tu servidor.Parámetros
8 · 0 obligatorios
message.received
opcional
Un cliente te escribe, por cualquier canal.
message.sent
opcional
Sale un mensaje: IA, operador, campaña, automatización, API.
message.status
opcional
Un mensaje de WhatsApp se entregó, se leyó o no se entregó (con el código de error de Meta).
campaign.started
opcional
Una campaña empieza a enviar.
campaign.completed
opcional
Una campaña ha terminado, con sus cifras.
campaign.failed
opcional
Una campaña se detuvo por un error.
template.status_changed
opcional
Una plantilla de WhatsApp se aprobó, se rechazó, se pausó o se desactivó, con el motivo.
booking.* / voice.*
opcional
Las citas de la Agenda y las llamadas de la Voice AI: mismas direcciones, misma firma.
¿Necesitas ayuda con la integración? info@sendapp.live