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 logicThe 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
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
| State | Meaning |
|---|---|
pending | Received, queued for processing |
processed | Processed successfully |
failed | Processing threw an error |
skipped | No 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
| Provider | Module that registers it | Description |
|---|---|---|
stripe | Billing | Payment, subscription and invoice events |
Adding a new provider
Implement the
WebhookProviderAdapterinterface:typescriptexport 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 } }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); } }Import
WebhooksModulein your module to get theWebhookProviderRegistry.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.