Dominando los Webhooks de la API REST de WhatsApp

¿Tus clientes escriben por WhatsApp y no reciben respuesta? Descubre cómo una solución multiagente evita mensajes perdidos, mejora tiempos de respuesta y convierte más ventas.
CONTÁCTANOS

Qué es: Un webhook es un endpoint HTTP (p. ej. POST /webhooks/whatz) donde WhatzMeAPI empuja eventos de WhatsApp en tiempo real (mensajes, entregas, lecturas).

1) Setup en 7 pasos

1. Publica POST /webhooks/whatz en HTTPS.
2. Configura la URL en WhatzMeAPI (panel/API).
3. Define un secreto para firma HMAC (X-Signature: sha256=<hex>).
4. Autentica la petición (Bearer/Basic/JWT).
5. Guarda message.key.id y responde 200 en <2s.
6. Procesa asíncrono (cola + worker + reintentos exponenciales).
7. Monitorea (logs estructurados, métricas, alertas).

2) Payloads típicos (resumen)

Texto entrante

{"event":"messages.upsert","messages":[{"key":{"id":"ID","fromMe":false,"remoteJid":"52155...@s.whatsapp.net"},"message":{"conversation":"Hola"}}]}

Estado de entrega/lectura

{"event":"messages.update","statuses":[{"id":"ID","status":"delivered"},{"id":"ID","status":"read"}]}

3) Endpoint mínimo (Express)

import express from 'express';
import crypto from 'crypto';
const app = express();
app.post('/webhooks/whatz', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.header('X-Signature');
  const h = crypto.createHmac('sha256', process.env.WHATZ_SECRET).update(req.body).digest('hex');
  if (!sig || sig.replace('sha256=', '') !== h) return res.sendStatus(401);
  const evt = JSON.parse(req.body.toString());
  // TODO: if (seen(evt.messages?.[0]?.key?.id)) return res.sendStatus(200);
  // TODO: enqueue(evt)
  return res.status(200).json({ ok: true });
});
app.listen(3000);

Laravel/Spring: misma lógica → leer cuerpo crudo, validar HMAC, ack y encolar.

4) Diseño rápido (contrato)

• Headers: Content-Type: application/json, Authorization, X-Signature.
• Idempotencia: clave = messages[0].key.id.
• Respuesta: 200 {"ok":true} (procesa luego).

5) Enviar respuesta al cliente (API de salida)

POST /messages/send  Authorization: Bearer <TOKEN>
{
  "to":"5215512345678","type":"text","text":{"body":"¡Hola!"}
}

6) Seguridad esencial

• HTTPS obligatorio · HMAC‑SHA256 · Auth (Bearer/Basic/JWT)
• Rate limit + WAF/IP allowlist · Logs sin PII · Rotación de secretos

7) Pruebas rápidas

• Postman (colección WhatzMeAPI) + variables TOKEN, WEBHOOK_URL.
• ngrok/Cloudflare Tunnel para exponer localhost.
• Envía mensaje real y verifica 200 + evento en cola.

8) Errores comunes (y fix)

• Procesar dentro del request → timeouts → ack + cola.
• No validar firma → spoofing → HMAC.
• Duplicados → reintentos → idempotencia por key.id.

Checklist final

[ ] HTTPS + Auth + HMAC · [ ] 200 en <2s · [ ] Cola + backoff · [ ] Métricas/alertas

Conoce WhatzMeAPI (API REST + Chatbot): WhatzMeApi