Guía de webhooks de WhatsApp: eventos, seguridad y reintentos

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

¿Cómo escribo un gestor fiable?

Haga tres cosas por este orden: guarde el evento sin procesar, confirme con un 2xx y procese después de forma asíncrona. El gestor siguiente sigue el patrón de nuestra documentación.

import express from "express";

const app = express();

// Capture el cuerpo sin procesar para guardarlo exactamente como se recibió.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // falló el almacenamiento: deje que se reintente el evento
    }
    res.sendStatus(200);          // confirme rápido
    queue.publish("status-events", req.body); // haga el trabajo real en otro lugar
  },
);

// Worker: procesamiento idempotente
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // asigne según el canal
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // mensaje desconocido: regístrelo e investigue
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // duplicado u obsoleto

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # falló el almacenamiento: deje que se reintente el evento
    queue.publish("status-events", raw)  # procese de forma asíncrona
    return "", 200               # confirme rápido

Los objetos db y queue son su propio almacenamiento y su propia cola de trabajos. El mapa rank es lo que hace idempotente el procesamiento: un evento duplicado u obsoleto no supone un avance, por lo que se ignora.

Reglas para un gestor fiable

• Responda en pocos segundos. No haga trabajo pesado antes de responder.
• Devuelva 2xx solo después de guardar el evento. Si falla el almacenamiento, devuelva 5xx.
• Deduplique por ID de mensaje. El mismo estado puede llegar más de una vez.
• No reenvíe nunca un mensaje desde el gestor. Decida los reintentos en un trabajo aparte, tras comprobar el estado.
• Conserve el cuerpo sin procesar para diagnosticar problemas y para reproducir eventos tras una corrección.

¿Cómo protejo un webhook de WhatsApp?

Depende de quién envíe a su endpoint. Meta firma los webhooks que envía a las apps que usted registra en Meta. La especificación de la API de OmniChannels.ai no define ninguna cabecera de firma de webhook, así que no espere a que exista.

Para el esquema de Meta, la documentación de Meta indica generar un hash HMAC-SHA256 a partir de la carga JSON con el secreto de su app y compararlo con el valor posterior a sha256= de la cabecera X-Hub-Signature-256. El propio HMAC está definido en la RFC 2104. Calcúlelo sobre los bytes sin procesar, no sobre un objeto reserializado, y compare en tiempo constante.

Para nuestro endpoint:

• Use solo HTTPS, con un certificado válido.
• Use una ruta larga e imposible de adivinar, y rótela si se filtra.
• Valide la forma del cuerpo y rechace todo lo inesperado.
• Trate los eventos como notificaciones. Antes de una acción irreversible, como un reembolso o un bloqueo por fraude, confirme el estado con una llamada de consulta.

¿Qué ocurre cuando falla la entrega?

Los reintentos dependen del remitente. La documentación de Meta dice que reintenta una entrega fallida con una frecuencia decreciente durante hasta 7 días, lo que puede producir notificaciones duplicadas. Es un motivo para ser idempotente aunque rara vez vea duplicados. Para los eventos de nuestra plataforma, confirme el comportamiento de los reintentos con su ingeniero de alta en lugar de suponer que coincide con el de Meta.

En cualquier caso, construya pensando tanto en la pérdida como en la duplicación: su endpoint puede estar caído durante un despliegue, y una regla de cortafuegos puede descartar peticiones en silencio.

¿Cómo recupero los eventos que faltan?

Consulte el lote, no reenvíe el mensaje.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id es el ID devuelto por la llamada de envío, y page empieza en cero. Ejecute una conciliación nocturna que lea los lotes del día anterior y rellene las lagunas.

Lista de verificación para solucionar problemas

1. ¿Está configurada la URL en la cuenta o subcuenta correcta?
2. ¿Se puede acceder al endpoint por HTTPS con un certificado válido?
3. ¿Responde con 2xx con rapidez, o agota el tiempo de espera?
4. ¿Está una regla de cortafuegos o de WAF bloqueando las peticiones?
5. ¿Registra el cuerpo sin procesar antes de analizarlo, para que un error del analizador no pueda ocultar el evento?

Ejemplo práctico: el flujo de notificaciones de un comercio

"Souq Rafiq" (ficticia), un comercio de los Emiratos Árabes Unidos, envía actualizaciones de pedidos por WhatsApp y quiere un estado exacto en su herramienta de pedidos.

1. Los pedidos se envían con sendbulk, y el batchId se guarda en el pedido. Consulte enviar un mensaje de WhatsApp por API.
2. El endpoint del webhook escribe cada evento en una tabla y después devuelve 200.
3. Un proceso de trabajo clasifica los estados y actualiza el estado del mensaje del pedido.
4. Los eventos FAILED crean una tarea para soporte con el motivo, y se valora un respaldo por SMS según el respaldo entre canales.
5. Los mensajes entrantes de los clientes se derivan a la bandeja compartida para que los agentes puedan responder dentro de la ventana.
6. Un proceso nocturno llama a bulk-insights para los lotes del día anterior y corrige lo que se haya perdido.

¿Cuáles son los errores habituales?

• Trabajo pesado antes de responder, que provoca tiempos de espera agotados y entregas repetidas.
• Confirmar antes de guardar, que pierde eventos cuando falla el almacenamiento.
• Fiarse del orden. Un SENT tardío que sobrescribe un DELIVERED.
• Programar contra la carga ilustrativa en lugar de contra eventos reales.
• Reserializar el JSON antes de comprobar una firma, lo que cambia los bytes.
• Reenviar desde el gestor, lo que puede crear un bucle.
• Límites: esta guía describe nuestro comportamiento documentado. La política de reintentos y los campos de la carga de su cuenta deben confirmarse durante el alta.

Cómo le ayuda OmniChannels.ai

OmniChannels.ai envía a su webhook, en un único formato normalizado, los estados de entrega y los mensajes entrantes de WhatsApp, SMS, RCS y otros canales, con webhooks distintos por subcuenta para los revendedores. BroadNet es un Meta Business Solution Provider oficial, por lo que los requisitos de webhook de la propia Meta se gestionan por usted, y usted trabaja con nuestra API. Lea la referencia de webhooks y la documentación de la API de WhatsApp, o vea cómo aparecen los eventos en la bandeja compartida.