Webhooks: cómo recibir mensajes y eventos

Un webhook es la dirección de tu sistema a la que la plataforma envía cada mensaje y cada evento. Así se configura y así debe responder.

Qué es un webhook

Un webhook es una llamada HTTP que la plataforma hace a tu servidor cuando ocurre algo: llega un mensaje, cambia el estado de un envío o se aprueba una plantilla. Tú expones una URL pública y la plataforma hace POST contra ella.

Es el mecanismo normal para atender conversaciones: sin webhook, tu sistema no se entera de lo que escribe el cliente.

Cómo debe responder tu endpoint

• Devuelve 2xx con cuerpo vacío. Si no respondes en menos de 10 segundos, la plataforma considera la notificación fallida y la reintenta un poco después.
• Responde rápido y procesa después: confirma la recepción al instante y encola el trabajo pesado. Entre 100 y 1.000 milisegundos es un buen tiempo de respuesta; cuanto más tardes, más se retrasan los mensajes siguientes.
• Acepta la cabecera User-Agent y los eventos de arranque de entorno de pruebas.
• La URL debe ser pública y aceptar POST con Content-Type: application/json.

Buenas prácticas

1. Idempotencia: guarda el identificador del mensaje y descarta duplicados. Los reintentos existen.
2. Responde 2xx aunque el procesamiento falle después: si devuelves error para forzar reintentos, acabarás recibiendo ráfagas.
3. Verifica el origen si tu infraestructura lo permite (lista de IPs o firma) y usa siempre HTTPS.
4. Un endpoint por entorno: no compartas producción con pruebas.

Qué vas a recibir

• Mensajes entrantes de texto, imagen, archivo, audio, video, ubicación y contactos.
• Respuestas a botones y a listas.
• Estados de tus envíos: enviado, entregado, leído, fallido.
• Eventos de sistema: cambios de estado de plantillas y de la cuenta.