Saltar al contenido principal

TEC-011 — API Webhooks

· 2 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Implementación de la mejora TEC-011 (API Webhooks), dentro de 6.3 Integración. El módulo pasa de notificar solo hacia dentro (Socket.io, notificaciones y correo) a notificar también hacia fuera: sistemas externos se suscriben a eventos y reciben notificaciones HTTP firmadas.


📋 Alcance​

RFEntregable
RF-TEC-011-01Configurar webhooks hacia sistemas externos
RF-TEC-011-02Enviar webhooks ante despachos, recepciones y alertas de stock
RF-TEC-011-03Configurar la URL y los eventos de cada webhook
RF-TEC-011-04Reintentar envíos fallidos y registrar su estado

⚙️ Cómo funciona​

  • Catálogo cerrado de 3 eventos: despacho.registrado, recepcion.registrada, alerta.stock. Los dos primeros se publican en los puntos de negocio (tras el commit de la transacción); el tercero lo emite un escaneo periódico que reutiliza la detección de alertas de stock y deduplica por (producto, almacén, tipo).
  • Firma HMAC-SHA256 por webhook: X-CCF-Signature = sha256(HMAC(secreto, timestamp + "." + cuerpoCrudo)), con X-CCF-Timestamp, X-CCF-Event, X-CCF-Event-Id y X-CCF-Delivery. El secreto se guarda cifrado en reposo (TEC-007) y se muestra una sola vez.
  • Entrega y reintentos: cada notificación se persiste en webhook_entregas (estado, intentos, código HTTP, respuesta, próximo intento). Un @Cron cada minuto reintenta con backoff exponencial; la cola BullMQ (TEC-002) es opcional y solo descarga el intento inmediato. Funciona sin Redis.
  • Administración web: página /webhooks (solo Administrador) con CRUD, prueba, rotación de secreto e historial con reintento manual.

🗄️ Base de datos​

Migración 032-create-webhooks con tres tablas: config_webhooks, webhook_entregas y webhook_alertas_stock (deduplicación del escáner).

🔐 Seguridad​

  • Secreto cifrado en reposo (AES-256-GCM, TEC-007) y nunca devuelto por la API.
  • CHECK de URL https?:// y rangos válidos de timeout/intentos.
  • Endpoints api/webhooks: escritura solo Administrador; lectura Administrador y Auditor.

✅ Verificación​

  • 33 pruebas nuevas de API (firma, servicio, planificador, configuración) y 3 de web.
  • tsc (API y web), ESLint y npm run build sin errores; suites sin regresiones propias.
  • Integración real 16/16 OK: receptor HTTP local, firma verificada contra el cuerpo crudo, secreto cifrado comprobado en la base, reintentos con backoff hasta fallido, recuperación por reintento manual y desactivación conservando el historial.