Build around events and webhooks

Register the destination#

The source contract documents POST /webhooks with url and eventTypes, and optional secret and description. Select only the event types required by the merchant workflow.

Verify the actual delivery#

The supplied webhook service signs delivery with HMAC when a secret is configured. Confirm the exact headers and payload format against your deployed contract before implementing verification; the tenant identifier alone is not verification.

Inspect delivery attempts#

GET /webhooks/{id}/deliveries lists deliveries and POST /webhooks/{id}/test initiates a test. Use these alongside your receiver logs to inspect the complete handoff.

Design for repetition and failure#

Make handlers appropriate for repeated delivery and reconcile incomplete work. The supplied service includes a retry mechanism; confirm its deployed policy rather than assuming a guaranteed schedule or delivery order.

The concrete source sender.

The supplied platform webhook service posts JSON.stringify(payload). This function does not add a separate outer event envelope. It signs that body only when the endpoint has a configured secret. The following describes the supplied implementation, rather than a live delivery guarantee.

The source signature calculation is HMAC-SHA256 using the endpoint secret and the exact request body. No timestamp component is included by this sender. Verify the raw received bytes rather than parsing and reformatting the JSON first.

Run an offline signature check.

Download the Node.js standard-library example ↗

node verify_webhook.mjs --self-test

The checked self-test accepts a matching body and rejects a changed body and malformed signature. It creates no endpoint and makes no network request. A production receiver also needs durable processing, appropriate access controls and a deliberate duplicate-event strategy.

For a locally saved body, set your own AGORA_WEBHOOK_SECRET privately in the environment, then pass the body file and signature header to the script. Do not place real secrets in this website or a shared code example.

Inspect delivery and retry behaviour separately.

The concrete sender uses a ten-second abort timeout and treats a successful HTTP response as delivered. Each attempt records its status and error. The source contains failed-delivery retry logic; it does not establish a retry schedule or a guarantee of exactly three total requests per event.

Confirm the deployed commerce-event dispatcher, scheduler and duplicate-delivery behaviour before relying on automatic redelivery. The extension SDK describes a separate declared subscription model; its retry comments must not be assumed to describe the REST sender.

Source-defined commerce events.

These names are present in the supplied commerce modules. A defined event does not by itself prove that it is connected to outbound delivery in a particular deployment.

order.placed.v1
order.confirmed.v1
order.processing.v1
order.shipped.v1
order.delivered.v1
order.completed.v1
order.cancelled.v1
order.refunded.v1
order.modified.v1

inventory.stock.adjusted.v1
inventory.stock.received.v1
inventory.stock.returned.v1
inventory.stock.damaged.v1
inventory.stock.transferred.v1
inventory.stock.config_updated.v1
inventory.stock.below_threshold.v1
inventory.stock.back_in_stock.v1
inventory.stock.reserved.v1
inventory.stock.reservation_released.v1
inventory.stock.reservation_committed.v1
inventory.stock.reservation_expired.v1

payment.intent_created.v1
payment.authorized.v1
payment.captured.v1
payment.failed.v1
payment.voided.v1
payment.refunded.v1
payment.cancelled.v1

Keep subscriptions within the right scope.

The REST routes use the current tenant context for endpoint and delivery access. The service supports exact event matches, an all-events wildcard and a trailing namespace wildcard. Inspect the actual subscription and authorisation contract for the environment you are building against.

The source test route emits a synthetic event through the matching-endpoint dispatcher. Do not assume that running it is isolated to only one endpoint. Use a controlled environment and inspect the matching subscriptions first.