Definición
Un webhook es una solicitud HTTP que una plataforma envía a una URL indicada por el cliente cada vez que ocurre un evento, como la entrega, lectura o fallo de un mensaje o la llegada de una respuesta de un cliente, de modo que el sistema se entera de inmediato sin necesidad de consultas periódicas (polling).
Se registra un endpoint (por ejemplo, https://example.com/hooks/messaging). Cuando se produce un evento, la plataforma envía una solicitud POST con un cuerpo JSON que lo describe: ID del mensaje, estado, marca de tiempo, canal y detalles del error. El servidor debe responder rápidamente con un código 2xx y procesar el evento de forma asíncrona.
Hay que diseñar para las condiciones reales de entrega: los webhooks pueden llegar tarde, desordenados o más de una vez. Conviene usar el ID del mensaje y el estado para eliminar duplicados, no retroceder nunca un estado (por ejemplo, de READ a DELIVERED) y mantener un manejador idempotente y seguro ante reintentos.
Seguridad: aceptar solo HTTPS, verificar una firma o un secreto compartido en cada solicitud y no confiar en la carga útil hasta haberla verificado. Convenciones del sector como la especificación Standard Webhooks describen patrones habituales de firma y reintento.
En mensajería, los webhooks alimentan los informes de entrega, las tasas de lectura, las respuestas entrantes, las bajas y las decisiones de respaldo entre canales.
OmniChannels.ai envía webhooks para los estados de entrega (SUBMITTED, SENT, DELIVERED, READ, FAILED, REJECTED), normalizados en un formato único para todos los canales.
Ejemplo
{"messageId":"msg_123","channel":"whatsapp","status":"DELIVERED","timestamp":"2026-10-10T09:15:02Z"}