Skip to main content

Webhooks (webhooks)

Outbound HMAC-signed event subscriptions. Domain events on the in-process event bus are bridged to a BullMQ queue; the worker signs and POSTs each delivery to the subscriber URL.

Public surface​

Verb + PathPurpose
GET /api/v1/admin/webhooksList subscriptions
POST /api/v1/admin/webhooksCreate — secret returned once. eventTypes must be deliverable
PATCH /api/v1/admin/webhooks/:idUpdate (status, eventTypes, url). Event types it adds must be deliverable
DELETE /api/v1/admin/webhooks/:idRemove
GET /api/v1/admin/webhooks/deliveriesRecent deliveries (filterable by status)
POST /api/v1/admin/webhooks/deliveries/:id/replayReplay a failed / dead_lettered delivery
GET /api/v1/admin/webhooks/event-typesThe event types other modules contribute, whose owner is switched on

Delivery contract​

Headers: Content-Type: application/json, X-Webhook-Event-Id, X-Webhook-Event-Type, X-Webhook-Signature-256, X-Webhook-Attempt. Receivers MUST verify the signature with timingSafeEqual and dedupe on the event id. The Subscribing to webhooks section of Endora's Integrations guide carries the verification example.

Retry model​

Up to 8 attempts per delivery, exponential backoff starting at 1 s, 10 s per-attempt timeout. Final attempt → dead_lettered. The replay endpoint copies a failed/dead-lettered row into a fresh pending delivery.

Delivery history retention​

Each delivery row keeps the event's payload as it was sent, and the receiver's response. A payload can hold personal data, such as the reason an operator gave for blocking an organization, so the history is kept for a limited time. Once a day, every finished delivery (succeeded, failed or dead_lettered) older than webhooks.delivery_retention_days is deleted. The default is 365 days, the same as the customer deletion retention window, so by the time a deleted customer is anonymized, the deliveries written before the deletion are already gone. A value outside 1–3650 whole days is read as the default. A pending or in_flight delivery is never deleted, however old it is. A deleted delivery can no longer be replayed. The check runs in the worker process and only while this module is on; while it is off nothing is deleted, and the first run after it is switched back on deletes what came due meanwhile.

The delivery queue keeps its own copy of each finished job in Redis, with the payload and the subscription's signing secret. That copy is bounded by the same window: a finished job is removed once it is older than webhooks.delivery_retention_days, and the queue also keeps no more than the latest 500 succeeded and 5 000 failed jobs. The daily check removes the expired jobs as well, so they go even when no new delivery finishes. A changed window applies to the jobs queued after the change and, at the next daily check, to the jobs already finished.

Which events are delivered​

An event is delivered only when it is bridged to the delivery queue. This module bridges two event types of its own accord, order.created.v1 and order.status_changed.v1; every other deliverable type is contributed by the module that emits it (next section). An event that is merely emitted on the in-process event bus is not delivered.

The two built-in names are one constant, WEBHOOK_BUILT_IN_EVENT_TYPES in @endora-commerce/contracts. The backend subscribes its bridge from it and the subscription form offers from it, so the form cannot offer an event that is not delivered.

A subscription may name only deliverable event types. Creating a subscription, or adding an event type to one, with a name that is neither built in nor contributed by a module that is switched on is refused with 422 WEBHOOK_EVENT_TYPE_NOT_DELIVERABLE; error.details.eventTypes carries the refused names.

Subscriptions saved before this rule are kept as they are. The rule is applied when a subscription is written and only to the names that write adds:

  • nothing is migrated or deleted, and listing never fails on a stored name;
  • such a subscription can still be paused, renamed, re-pointed and deleted, and an eventTypes update may keep a name it already carries;
  • a name that has been removed cannot be added back;
  • the Webhooks screen shows every stored name and marks the ones that are not delivered;
  • delivery is unaffected — a name nothing bridges receives nothing, as before.

Event types contributed by other modules​

Any other module can offer event types of its own through the webhookEventRegistry — this module names no other module's event.

A contributing module pushes its event names from a boot hook that does nothing else:

ctx.onBoot(() => {
const registry = lazyPort<WebhookEventRegistryPort>(ctx, 'webhookEventRegistry');
registry.register({ ownerModuleId: 'acme_loyalty', eventType: 'acme_loyalty.points_granted.v1' });
});

and declares the edge in its manifest: nonBindingDependencies: [{ moduleId: 'webhooks', name: 'webhookEventRegistry', kind: 'contributes-to' }].

What follows from a push:

  • The event type is bridged to the delivery queue exactly as the built-in ones are — through this module's own subscription, so it stops when this module is switched off. The event's payload is sent whole, so an event a module offers is a public contract of that module.
  • It is offered on the subscription form — after the built-in types — and accepted by the API while its owner is switched on. GET /api/v1/admin/webhooks/event-types answers { "data": [{ "ownerModuleId", "eventType" }] }.
  • While the owner is switched off the type is not offered, a new subscription to it is refused, and nothing of that type is delivered — the bridge asks for the owner's presence per event, before it looks at any subscription. Subscriptions that name it are kept and receive nothing until the owner is back.
  • A subscription bound to one organization receives a contributed event only when its payload carries that organizationId.
  • Pushing the same type twice, or a type this module already bridges, delivers once.

Who contributes today​

ModuleEvent typesPayload documented on
catalogproduct.created.v1, product.updated.v1, product.archived.v1the catalog module page
quote_requestsrfq.created.v1, rfq.expired.v1the quote_requests module page
credit_limitscredit_limit.adjusted.v1the credit_limits module page
crmcrm.opportunity.status_changed.v1, crm.opportunity.created.v1, crm.opportunity.closed.v1packages/contracts/src/crm.ts

One rule for all of them: the module that emits an event is the one that offers it. order.created.v1 and order.status_changed.v1 are the two this module bridged before the registry existed, and they stay built in.

Who receives an event​

Subscriptions are created by an administrator holding integrations:manage; there is no customer-facing way to create one. A subscription is either platform-wide or bound to one organization, and the bridge decides per event:

  • an event whose payload carries an organizationId reaches every platform-wide subscription naming its type, and the subscriptions bound to that organization — quote-request, credit-limit, order and CRM events are of this kind;
  • an event whose payload carries none reaches platform-wide subscriptions only — product events are of this kind, so a subscription bound to an organization never receives one.

Subscriptions have no sales-channel dimension: an event is not filtered by the channel it happened on.

What one event costs​

For each bridged event the bridge reads the active subscriptions once and adds one job to the delivery queue per subscription that names the type and passes the organization rule. With no such subscription nothing is added to the queue. Nothing is batched or coalesced: a bulk edit, an import or a PIM synchronisation that writes a thousand products is a thousand product.updated.v1 events and, per subscription naming that type, a thousand deliveries.

Entities​

Webhook (name, url, eventTypes, secret, status), WebhookDelivery (per-attempt audit row).

Extension points​

  • Custom signing scheme — webhook-delivery-worker.ts#process is the single place HMAC headers are set; replace with a different signature format or add a JWS variant here.
  • Subscription scope policy — webhook-service.ts accepts any deliverable event type; layer authorization (e.g. only certain integrations may subscribe to one module's events) by injecting a policy callback.