Skip to content

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 negocio

El 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 ​

http
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 ​

EstadoSignificado
pendingRecibido, en cola para procesar
processedProcesado exitosamente
failedEl procesamiento lanzó un error
skippedNo 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 ​

ProveedorMódulo que lo registraDescripción
stripeBillingEventos de pagos, suscripciones y facturas

Añadir un nuevo proveedor ​

  1. Implementar la interfaz WebhookProviderAdapter:

    typescript
    export 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
      }
    }
  2. 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);
      }
    }
  3. Importar WebhooksModule en el módulo para obtener el WebhookProviderRegistry.

  4. 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.