Webhook en producción: firma, reentrega e idempotencia (lo que nadie prueba antes)

Todo webhook funciona en la primera prueba. Envías un mensaje, el evento llega, el código responde. Lo que falla es el webhook en producción, con volumen — y falla de tres formas que la prueba manual nunca muestra.

Si tu problema es que el evento no llega, el camino es otro: las 7 causas y cómo probarlo. Acá el evento llega. El problema es lo que pasa después.

Problema 1 — El mismo evento procesado dos veces

Por qué pasa

La plataforma reenvía cuando no recibe 200 rápido. Eso es correcto: sin reentrega, un evento se perdería cada vez que tu servidor se reinicia. El comportamiento existe para que no pierdas mensajes.

El efecto colateral es que el mismo evento puede llegar dos o tres veces. Y entonces:

• el bot responde lo mismo tres veces;
• el CRM crea tres registros del mismo contacto;
• el cobro se emite dos veces.

La corrección, en dos capas

Capa 1 — responder 200 antes de procesar. Resuelve la mayoría de los casos en el origen:

app.post('/webhook/wame', (req, res) => {
  res.sendStatus(200);
  cola.add(req.body).catch(console.error);
});

Capa 2 — idempotencia. La capa 1 reduce el duplicado; no lo elimina. La red falla, y una respuesta puede perderse en el camino después de que tu servidor ya procesó. La garantía real es tratar el messageId como clave única:

async function procesar(evento) {
  const msg = evento?.entry?.[0]?.changes?.[0]?.value?.messages?.[0];
  if (!msg) return;

  // SETNX con expiración: escribe solo si todavía no existe.
  // La operación es atómica, así que dos entregas simultáneas no
  // pasan las dos — que es el caso que un "if (existe)" seguido
  // de "escribe" deja escapar.
  const inedito = await redis.set(`wh:${msg.id}`, '1', {
    NX: true,
    EX: 60 * 60 * 24,
  });
  if (!inedito) return;   // ya procesamos este evento

  await responderCliente(msg);
}

Sin Redis, la misma idea con una tabla y una restricción de unicidad en message_id funciona igual: intenta insertar, y si viola la restricción, ignora el evento.

El orden importa. Guarda la marca antes de actuar, no después. Marcarla después deja la ventana abierta justo en el intervalo en que ocurre el procesamiento, que es cuando suele llegar la reentrega.

Problema 2 — Endpoint abierto a cualquiera

Si tu URL de webhook es https://api.tuempresa.com/webhook/whatsapp, cualquiera que la descubra puede publicar un JSON falso. Según lo que haga tu handler, eso es un mensaje enviado en nombre de tu cliente o un registro falso en la base.

Capa 1: ruta secreta

El mínimo aceptable, y lleva un minuto:

https://api.tuempresa.com/webhook/wame/a8f3d92e4b17c05f

El secreto está en la ruta. No es criptografía, pero elimina al escáner automático — y es infinitamente mejor que /webhook.

Capa 2: validar la firma

Cuando la plataforma firma el cuerpo, verifica la firma. Y verifícala bien:

import crypto from 'node:crypto';

function firmaValida(req) {
  const recibida = req.get('X-Hub-Signature-256');
  if (!recibida) return false;

  const esperada = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    // El cuerpo CRUDO, no el objeto reserializado: JSON.stringify
    // puede reordenar claves y cambiar espaciado, y el hash nunca coincide.
    .update(req.rawBody)
    .digest('hex');

  // Comparación en tiempo constante: `===` filtra información por el
  // tiempo de respuesta y permite descubrir la firma byte a byte.
  const a = Buffer.from(recibida);
  const b = Buffer.from(esperada);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Para tener req.rawBody en Express:

app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}));

Capa 3: un secreto por cliente

Si entregas sistemas a varios clientes, no uses el mismo secreto para todos. Un secreto por instancia, guardado junto al registro del cliente: si se filtra uno, rotas ese, no los treinta.

Problema 3 — Eventos fuera de orden

No hay garantía de orden. Dos mensajes enviados en secuencia pueden llegar invertidos, y una reentrega puede poner un evento viejo después de uno nuevo.

Eso rompe una lógica del tipo "el último mensaje define el estado de la conversación":

// frágil: depende del orden de llegada
conversacion.ultimoMensaje = msg.text.body;

// robusto: el evento más nuevo gana, llegue cuando llegue
if (!conversacion.ultimoTs || msg.timestamp > conversacion.ultimoTs) {
  conversacion.ultimoMensaje = msg.text.body;
  conversacion.ultimoTs = msg.timestamp;
}

Si tu máquina de estados depende de la secuencia, ordena por timestamp del evento. Nunca por el orden en que tu servidor lo recibió.

La arquitectura que resuelve los tres de una vez

app.post('/webhook/wame/:secreto', async (req, res) => {
  // 1. autenticación, antes de cualquier trabajo
  if (req.params.secreto !== process.env.WEBHOOK_PATH_SECRET) {
    return res.sendStatus(404);   // 404 y no 403: no confirmes que existe
  }
  if (!firmaValida(req)) return res.sendStatus(401);

  // 2. confirma al instante
  res.sendStatus(200);

  // 3. encola; el procesamiento ocurre fuera de la petición
  await cola.add('webhook', req.body, {
    // el propio id del evento como clave: la cola descarta el
    // duplicado antes incluso de que el worker despierte
    jobId: req.body?.entry?.[0]?.changes?.[0]?.value?.messages?.[0]?.id,
  });
});

Con BullMQ, el jobId ya da la idempotencia gratis — un job con id repetido se descarta.

El checklist antes de publicar

• Responde 200 antes de procesar
• messageId guardado como clave única, antes de actuar
• Ruta del webhook con secreto
• Firma validada sobre el cuerpo crudo, con comparación en tiempo constante
• Secreto por instancia, no global
• Estado resuelto por timestamp, no por orden de llegada
• Estado de entrega tratado aparte del mensaje recibido
• Un error en el procesamiento no tumba la respuesta del endpoint

Por qué esto es más simple con un solo webhook

Cada punto de arriba es trabajo por integración. Con tres canales en tres plataformas distintas, es tres veces todo: tres validaciones de firma, tres formatos de id, tres lugares donde equivocarse.

Como los tres canales llegan en el mismo sobre, el checklist se escribe una vez y vale para los tres — el campo provider dice el canal y nada más cambia.