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 corresponding capability handler.
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. It checks that the capability handler and endpoint adapter exist before mounting the route; 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. The adapter and handler own provider-specific verification and event processing, with idempotency handling in that pipeline. 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 |
| Adapter and capability handler | Interpret and process the verified 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.