Webhooks: receptor seguro en Node.js

Descargue el receptor ejecutable. Valida firmas, rechaza replays antiguos y guarda una bandeja SQLite antes de responder. Requiere Node.js 24 o superior, sin paquetes adicionales.

PreparaciónCopiar enlace

1. Configure NOVODID_WEBHOOK_SECRET en un cofre o archivo privado. Use el secreto de firma del webhook, no el token API.
2. Configure NOVODID_WEBHOOK_DB en almacenamiento privado persistente; por defecto ./data/events.sqlite. PORT es 8787.
3. Ejecute con Node.js y publique /webhook detrás de un proxy HTTPS.
4. Registre esa URL HTTPS en Desenvolvedores → Webhooks y seleccione eventos. No se aceptan localhost, redes privadas ni redirects.
5. Use la prueba del panel y revise entregas. Se responde 202 solo tras guardar.

ValidacionesCopiar enlace

• HMAC-SHA256 de timestamp + punto + cuerpo bruto, comparado en tiempo constante con X-Novodid-Signature.
• X-Novodid-Timestamp con tolerancia de cinco minutos. Sincronice el reloj.
• Cuerpo máximo de 256 KiB, versión v1 y evento conocido.
• Duplicación por id del evento, no de cada intento. Un mismo id con contenido distinto se rechaza.

La tabla inbox guarda JSON, tipo y estado pending. El ejemplo recibe y persiste, pero usted debe implementar un trabajador separado e idempotente. Marque procesado solo tras completar su lógica. No suponga orden ni entrega única.

Seguridad y mantenimientoCopiar enlace

Los payloads pueden contener datos personales y SMS. Restrinja almacenamiento, backups y acceso; defina retención. No suba la base a Git. Al rotar el secreto actualice entorno y reinicie. Conserve la base entre reinicios. No registre tokens, secretos, cuerpos completos ni firmas en logs públicos.

401 indica problema de firma/reloj; 413, tamaño excesivo; 409, conflicto de id; 503, fallo de persistencia. Revise Entregas antes de reenviar. La plataforma permite ocho segundos por entrega: confirme pronto tras guardar y deje trabajo pesado al trabajador. Consulte payloads, eventos y reintentos en la guía de API.