TEC-011 — API Webhooks
· 2 min de lectura
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
| RF | Entregable |
|---|---|
| RF-TEC-011-01 | Configurar webhooks hacia sistemas externos |
| RF-TEC-011-02 | Enviar webhooks ante despachos, recepciones y alertas de stock |
| RF-TEC-011-03 | Configurar la URL y los eventos de cada webhook |
| RF-TEC-011-04 | Reintentar 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)), conX-CCF-Timestamp,X-CCF-Event,X-CCF-Event-IdyX-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@Croncada 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.
CHECKde URLhttps?://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 ynpm run buildsin 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.
