Enrutamiento y capacidades

Cuando un usuario responde a tu DID, o cuando el operador confirma la entrega, tu sistema recibe un webhook. Ese endpoint es público por definición, así que cualquiera puede llamarlo. La firma HMAC es lo que te permite distinguir un evento legítimo de uno falsificado.

Firmar y verificar

El emisor calcula HMAC-SHA256(secret, body) y lo envía en un header. Tú recalculas con el mismo secreto sobre el cuerpo crudo, exactamente como llegó, y comparas en tiempo constante. mx.webhook.sign usa WebCrypto real: el hex que ves es un HMAC auténtico.

 app.post("/webhooks/votp", express.json(), (req, res) => {
   // req.body is already parsed JSON: re-serializing it
   // almost never matches the bytes that were actually signed.
   const body = JSON.stringify(req.body);
   if (!verify(body, req.headers["x-votp-signature"])) {
     return res.status(401).end();
   }
   res.status(200).end();
 });

Capacidades por número

No todo número sirve para todo. Antes de enrutar, consulta las capacidades del DID (SMS entrante, SMS saliente, voz) y el país de destino. Un error común es intentar SMS desde un fijo habilitado solo para voz: el envío falla en silencio.

Reintentos e idempotencia

La mayoría de los proveedores reintentan la entrega de un webhook si tu endpoint no responde 200 a tiempo, lo que significa que puedes recibir el mismo evento dos o tres veces. Si procesas la confirmación de entrega sin controlar duplicados, puedes marcar como entregado un mensaje y luego revertirlo por error, o duplicar efectos secundarios como notificaciones al usuario.

La solución habitual es tratar el id del evento como clave de idempotencia: antes de procesar, revisa si ya existe un registro con ese id, y si existe, responde 200 sin reprocesar nada. Es una guarda barata comparada con el costo de depurar efectos duplicados en producción.