Webhooks
El módulo de webhooks recibe y procesa eventos de proveedores externos (pagos, comunicaciones, etc.) de forma genérica y extensible. Añadir un nuevo proveedor solo requiere implementar un adaptador — el controlador HTTP, la persistencia y el procesamiento asíncrono son compartidos.
Cómo funciona
POST /webhooks/:provider
↓
Buscar adaptador registrado
↓
Verificar firma criptográfica → 400 si inválida
↓
Comprobar idempotencia → 200 si ya existe
↓
Guardar registro pendiente en BD
↓
Encolar job asíncrono
↓
Devolver { "received": true } inmediatamente
↓
[background] ProcessWebhookHandler
↓
Adaptador.handleEvent() → lógica de negocioEl procesamiento real ocurre en background, sin bloquear la respuesta al proveedor. Si el procesamiento falla, el evento queda en estado failed para trazabilidad y el job se reintenta automáticamente (backoff exponencial); tras agotar los intentos va a dead-letter (ver Jobs). La re-entrega del mismo evento por el proveedor se ignora por idempotencia, así que el reintento del job es la vía de recuperación automática.
Endpoint
POST /webhooks/:provider
Content-Type: application/json
<payload sin parsear>El parámetro :provider identifica al proveedor (ej. stripe). No requiere token JWT — la autenticación la realiza la verificación de firma del propio proveedor.
Rate limit: 20 peticiones/min por IP (429 Too Many Requests si se supera). El límite es más alto que en otros endpoints públicos porque este tráfico es de proveedor a servidor (p. ej. Stripe puede enviar varios eventos en poco tiempo para una sola acción del cliente), no de un único actor humano.
Estados de un evento
| Estado | Significado |
|---|---|
pending | Recibido, en cola para procesar |
processed | Procesado exitosamente |
failed | El procesamiento lanzó un error |
skipped | No hay adaptador registrado para el proveedor |
Idempotencia
Cada evento se identifica por (provider, externalEventId). Si el mismo evento llega dos veces (reintento del proveedor o condición de carrera), el segundo se ignora y se devuelve { "received": true } igualmente. El índice único en BD garantiza la unicidad incluso bajo concurrencia.
Proveedores disponibles
| Proveedor | Módulo que lo registra | Descripción |
|---|---|---|
stripe | Billing | Eventos de pagos, suscripciones y facturas |
Añadir un nuevo proveedor
Implementar la interfaz
WebhookProviderAdapter:typescriptexport class MiProveedorAdapter implements WebhookProviderAdapter { readonly providerName = 'mi-proveedor'; verifyAndParse( rawBody: Buffer, headers: Record<string, string>, ): NormalizedWebhookEvent { // Verificar firma y devolver evento normalizado } async handleEvent( eventType: string, data: Record<string, unknown>, ): Promise<void> { // Lógica de negocio específica del proveedor } }Registrar el adaptador en el módulo correspondiente al inicializar:
typescript@Injectable() class MiWebhookBootstrap implements OnModuleInit { constructor( private readonly registry: WebhookProviderRegistry, private readonly adapter: MiProveedorAdapter, ) {} onModuleInit(): void { this.registry.register(this.adapter); } }Importar
WebhooksModuleen el módulo para obtener elWebhookProviderRegistry.Añadir el proveedor a la tabla anterior en esta página.
Multi-tenancy
Cada adaptador es responsable de resolver el companyId a partir de los datos del evento. El módulo genérico no sabe nada de tenants — esa lógica vive en cada adaptador.