Skip to content

Webhooks ​

The webhooks module receives and processes events from external providers (payments, communications, etc.) generically and extensibly. Adding a new provider only requires implementing an adapter — the HTTP controller, the persistence and the asynchronous processing are shared.

How it works ​

POST /webhooks/:provider
        ↓
   Look up the registered adapter
        ↓
   Verify the cryptographic signature → 400 if invalid
        ↓
   Check idempotency → 200 if it already exists
        ↓
   Store a pending record in the database
        ↓
   Enqueue an asynchronous job
        ↓
   Return { "received": true } immediately
        ↓
   [background] ProcessWebhookHandler
        ↓
   Adapter.handleEvent() → business logic

The real processing happens in the background, without blocking the response to the provider. If processing fails, the event stays in the failed state for traceability and the job is retried automatically (exponential backoff); once attempts are exhausted it goes to dead-letter (see Jobs). Re-delivery of the same event by the provider is ignored by idempotency, so the job retry is the automatic recovery path.

Endpoint ​

http
POST /webhooks/:provider
Content-Type: application/json
<unparsed payload>

The :provider parameter identifies the provider (e.g. stripe). It requires no JWT — authentication is the provider's own signature verification.

Rate limit: 20 requests/min per IP (429 Too Many Requests when exceeded). The limit is higher than on other public endpoints because this traffic is provider-to-server (e.g. Stripe may send several events in a short window for a single customer action), not a single human actor.

Event states ​

StateMeaning
pendingReceived, queued for processing
processedProcessed successfully
failedProcessing threw an error
skippedNo registered adapter for the provider

Idempotency ​

Each event is identified by (provider, externalEventId). If the same event arrives twice (a provider retry or a race condition), the second one is ignored and { "received": true } is returned all the same. The database's unique index guarantees uniqueness even under concurrency.

Available providers ​

ProviderModule that registers itDescription
stripeBillingPayment, subscription and invoice events

Adding a new provider ​

  1. Implement the WebhookProviderAdapter interface:

    typescript
    export class MyProviderAdapter implements WebhookProviderAdapter {
      readonly providerName = 'my-provider';
    
      verifyAndParse(
        rawBody: Buffer,
        headers: Record<string, string>,
      ): NormalizedWebhookEvent {
        // Verify the signature and return a normalized event
      }
    
      async handleEvent(
        eventType: string,
        data: Record<string, unknown>,
      ): Promise<void> {
        // Provider-specific business logic
      }
    }
  2. Register the adapter in the corresponding module at startup:

    typescript
    @Injectable()
    class MyWebhookBootstrap implements OnModuleInit {
      constructor(
        private readonly registry: WebhookProviderRegistry,
        private readonly adapter: MyProviderAdapter,
      ) {}
    
      onModuleInit(): void {
        this.registry.register(this.adapter);
      }
    }
  3. Import WebhooksModule in your module to get the WebhookProviderRegistry.

  4. Add the provider to the table above on this page.

Multi-tenancy ​

Each adapter is responsible for resolving the companyId from the event data. The generic module knows nothing about tenants — that logic lives in each adapter.