Webhooks — Introducción

Un webhook es un aviso que Wasapi envía a un servidor suyo cada vez que ocurre algo en su
cuenta: llega un mensaje, se crea un contacto, cambia el estado de un envío. En vez de que su
sistema pregunte cada tanto si hay novedades, Wasapi se las manda en el momento.

Cómo se configura

1. Entre a Configuración → Desarrolladores → Webhooks en la plataforma.
2. Elija el evento que quiere recibir.
3. Ponga la URL pública de su servidor.
4. En los eventos que dependen de una línea, marque de qué números quiere recibirlos. En los
   eventos de Instagram y Messenger, marque de qué canales: ahí el canal es obligatorio.

Puede tener varias URLs para un mismo evento: cada una recibe una copia.

El filtro por línea

De los 16 eventos de WhatsApp, 13 se filtran por número y 3 no. Los 4 eventos de Instagram y
Messenger se filtran por canal social, nunca por número (ver
Eventos de Instagram y Messenger):

⚠️ Si conecta una línea nueva, no queda suscrita automáticamente. Los webhooks
existentes siguen apuntando a las líneas que usted marcó cuando los creó. Es la causa más
común de «configuré el webhook y no llega»: revise que la línea nueva esté marcada.

Cómo se entrega

Su endpoint tiene 4 segundos

Wasapi corta la conexión a los 4 segundos y lo cuenta como fallo. Si su endpoint hace
trabajo pesado —consultar otra API, escribir en varias tablas, generar un PDF— no lo haga
dentro del request: guarde el payload, responda de inmediato y procese después, en
segundo plano.

Qué se considera entrega exitosa

Cualquier código 2xx. Cualquier otra cosa (4xx, 5xx, timeout, error de conexión) se
reintenta hasta 3 veces en total y después se descarta: no hay bandeja de reenvío ni
notificación de fallo.

Consecuencia práctica: si su servidor estuvo caído más de ~2 minutos, esos eventos se
perdieron. Para datos que no puede perder, complemente el webhook con una lectura periódica
de la API REST.

Reintentos ⇒ su endpoint debe ser idempotente

Un reintento envía el mismo evento otra vez. Si su servidor recibió el aviso pero
respondió tarde o con un 500 después de haber guardado, va a recibirlo repetido.

Use una llave natural para descartar duplicados:

Tampoco hay garantía de orden. Dos eventos disparados con milisegundos de diferencia
pueden llegar al revés. No asuma que receive_message llega antes que el
update_contact que provocó.

Seguridad del endpoint

Como los webhooks no van firmados, cualquiera que descubra su URL puede enviarle datos
falsos. Recomendaciones:

• Use una URL larga y no adivinable, o agregue un token en el query string
  (https://suservidor.com/wasapi?token=…) y valídelo.
• Sirva el endpoint por HTTPS, con un certificado válido.
• Trate el contenido como dato no confiable: valide antes de insertar.

El envoltorio

Todos los eventos llegan con la misma forma:

{
  "event": "receive_message",
  "data": {
    "...": "los campos del evento",
    "version": 1
  }
}

• event — el nombre del evento, igual al que activó en la plataforma.
• data — el contenido, distinto según la familia de evento.
• data.version — la versión del contrato. Hoy siempre 1.

Los 20 eventos

Compatibilidad: qué podemos cambiar y qué no

Qué significa esto para su integración: debe tolerar campos que no conoce. Es la única
condición para que un cambio aditivo no la rompa.

// ✅ Tome lo que necesita
$telefono = $data['phone'] ?? null;

// ❌ No inserte el payload completo a ciegas:
// un campo nuevo rompe el INSERT
$db->insert('mensajes', $data);

Qué leer ahora

La página más importante es Identidad del contacto:
explica cómo saber a qué persona corresponde cada evento, incluido el caso de los contactos
que ocultan su número de teléfono.