Receive provider events through their declared integration
Providers can notify the application when something changes in their system. Wildo registers inbound routes from an enabled provider’s webhook declaration and sends verified events to the handler that owns them. Stripe declares one for billing events, and Resend one for email the application receives.
This is different from sending your application’s events to customer endpoints. The provider defines the incoming event format and verification contract; the application enables and configures the integration.
Example — Receive a billing update
A billing provider sends a subscription event to the application. The registered webhook path verifies the provider’s request and resolves the billing account context before dispatching the update.
For engineers
Stripe declares its billing API protocol separately from WEBHOOK_ORIGINATOR. Enable the protocols required by the integration and supply STRIPE_WEBHOOK_SECRET as backend secret configuration. Register the endpoint with the provider using the actual deployed API address.
This selected protocol entry comes from stripe.backend.module.ts. Documentation comments are omitted; the provider’s other protocols and module registration remain outside this excerpt.
protocol: "WEBHOOK_ORIGINATOR",
runtimeContract: {
kind: ProviderProtocolRuntimeKind.WEBHOOK_ORIGINATOR,
secretRef: "STRIPE_WEBHOOK_SECRET",
signatureHeaderName: "stripe-signature",
endpoints: [
{
key: 'billing',
capability: BUILTIN_PROVIDER_CAPABILITY.BILLING,
signatureConfig: {
algorithm: Hook_SignatureAlgorithm.HMAC_SHA256,
},
triggerStrategy: Hook_TriggerStrategy.WEBHOOK,
eventTypes: [...STRIPE_BILLING_EVENT_TYPES],
scopeBinding: {
mode: 'polymorphic',
payloadScopeIdPath: 'data.object.customer',
lookupField: 'providerCustomerId',
variants: STRIPE_BILLING_ACCOUNT_WEBHOOK_VARIANTS,
},
},
],
},
The highlighted scope binding matches data.object.customer through providerCustomerId to the configured billing-account variants. The endpoint key supplies the route segment; its capability selects the registered billing handler. Do not infer the tenant from an unverified arbitrary request parameter.
Register a complete receiver, not merely a route name
WebhookAutoController discovers enabled provider endpoint declarations. Before mounting a route it checks that something can dispatch the event, a capability handler or an engine handler the endpoint is bound to, and that something can verify it, the provider’s adapter or the engine itself. An incomplete combination is withheld and reported rather than producing a route that can never dispatch.
The request path preserves raw body bytes for signature verification. Stripe’s adapter verifies its HMAC signature and the billing handler processes the event, with idempotency handling in that pipeline. Resend’s endpoint declares the Svix scheme, which the engine verifies without a provider adapter; each notification is stored once, answered, and processed by a worker that retries it. Custom providers must supply the corresponding endpoint contract and processing integration; copying a route declaration alone is insufficient.
| Integration piece | Responsibility |
|---|---|
| Provider runtime contract | Endpoint key, signature source and event vocabulary |
| Backend secret configuration | Verification material for the deployed endpoint |
| Provider adapter or engine verifier, and the owning handler | Verify, interpret and process the event |
| Scope binding | Resolve the event’s customer/account context |
A raw-body signature integration test exercises the request pipeline, while a production connection still needs the provider’s real delivery setup. Preserve the raw body until verification, and keep inbound verification separate from the ES256 contract used for Wildo’s outbound customer webhooks.