Recibir mensajes entrantes con webhooks

Qué son los webhooks entrantes

Los webhooks de mensajes entrantes permiten que Zapini notifique a tu sistema, en tiempo real, cada vez que llega un nuevo mensaje a tu instancia de WhatsApp. En lugar de consultar la API repetidamente, Zapini realiza una solicitud POST a la URL que registres.

Paso 1 — Crear un endpoint público

Crea un endpoint HTTPS en tu servidor que acepte solicitudes POST con cuerpo JSON. Debe responder rápidamente con HTTP 200 para confirmar la recepción. Realiza el procesamiento pesado de forma asíncrona para no retrasar la respuesta.

💡 Consejo: usa siempre HTTPS en el endpoint del webhook y valida el origen de la solicitud antes de confiar en el contenido.

Paso 2 — Registrar la URL del webhook

Indica la URL de tu endpoint en la configuración de la instancia. A partir de ahí, cada mensaje recibido genera una llamada a tu webhook.

Paso 3 — Tratar el payload

El cuerpo enviado a tu endpoint incluye datos del mensaje recibido, como el remitente, el contenido y los identificadores. Un ejemplo simplificado:

{
  "event": "message.received",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "from": "+5511999999999",
    "sender_name": "Maria",
    "type": "text",
    "message": "Hola, me gustaría más información",
    "received_at": "2026-06-13T10:30:00Z"
  }
}

En tu servidor, lee el JSON, registra el mensaje y dispara la lógica que necesites (abrir un ticket, actualizar un CRM, llamar a la API para responder, etc.).

Paso 4 — Probar y validar

Envía un mensaje real al número de la instancia y confirma que tu endpoint recibió la llamada. Revisa los registros de tu servidor y asegúrate de responder con HTTP 200.

Buenas prácticas

1. Responde rápido (200) y procesa en segundo plano.
2. Gestiona la recepción de forma idempotente, usando el identificador del mensaje para evitar duplicados.
3. Implementa reintentos y supervisa los fallos en tu endpoint.
4. Para enviar respuestas automáticas, combina el webhook con el endpoint de envío de mensajes de la API.