Integrar WhatsApp con Webhook

Paso a paso

1. 1

   Crea el endpoint que recibirá los eventos

   En tu backend, expón una ruta pública que acepte POST, por ejemplo POST https://tusistema.com/webhooks/zapzap. Debe leer el cuerpo JSON de la solicitud y responder rápido con un status 2xx (200 o 204). Responder fuera del rango 2xx hace que el evento se trate como fallo y se reenvíe. Si todavía no tienes una URL pública en desarrollo, levanta un túnel con ngrok (ngrok http 3000) y usa la URL https generada.

2. 2

   Deja el endpoint accesible e idempotente

   Asegúrate de que la URL responda por HTTPS y que ninguna autenticación bloquee el POST del proveedor (o permite la IP/ruta del webhook). Trata el payload como potencialmente duplicado: guarda el ID del evento o del mensaje e ignora las reentregas ya procesadas. Así, si el mismo evento llega dos veces por un reintento, no respondes al cliente por duplicado.

3. 3

   Registra la URL del webhook en tu instancia de ZapZap API

   En el panel de ZapZap API, abre la instancia de WhatsApp y entra en la sección de Webhook. Pega la URL de tu endpoint y selecciona los eventos que quieres recibir, como mensaje recibido y estado de entrega. Guarda. Desde ahí, cada evento de esa instancia se entregará en tu endpoint. Los nombres exactos de los eventos y el formato del payload están en la documentación en https://api.zapzapapi.com/llms.txt.

4. 4

   Procesa el evento y dispara la respuesta por REST

   Cuando llegue el POST, extrae del cuerpo el número del remitente y el texto del mensaje. Ejecuta tu lógica (consultar un pedido, activar una IA, guardar en el CRM) y responde llamando al endpoint de envío de ZapZap API con los headers x-api-key y x-api-secret. Devuelve siempre 2xx en el webhook, aunque el procesamiento pesado continúe en segundo plano, para no trabar la cola de entrega.

5. 5

   Prueba de punta a punta en producción

   Envía un mensaje real al número de la instancia y confirma en los logs de tu servidor que el POST llegó con el payload esperado. Luego valida que la respuesta automática salió por WhatsApp. Monitorea los logs de entrega del webhook en el panel: las entregas non-2xx quedan registradas para diagnóstico, así que ahí investigas si tu endpoint rechazó algún evento.

// Tu endpoint recibe el evento (Express)
app.post('/webhooks/zapzap', (req, res) => {
  res.sendStatus(200); // responde 2xx primero
  const { numero, texto } = req.body; // campos ILUSTRATIVOS, ver doc
  // tu logica aqui, luego responde por WhatsApp:
});

// Enviar respuesta por REST (campos exactos en la doc)
fetch('https://api.zapzapapi.com/api/v1/{instanceId}/send/text', {
  method: 'POST',
  headers: {
    'x-api-key': 'TU_API_KEY',
    'x-api-secret': 'TU_API_SECRET',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ numero: '5511999999999', texto: '¡Recibido!' })
});
// Estructura exacta de rutas y campos: https://api.zapzapapi.com/llms.txt