Build a webhook receiver EN
Verify raw-body signatures, deduplicate deliveries and handle retries without assuming exactly-once business effects.
A subscription belongs to one store. Manage it in admin under Webhooks or
through POST /api/v1/webhooks with a REST key carrying webhooks:manage.
The event catalogue at GET /api/v1/webhooks/events is public; that does not make
subscription-management endpoints public.
Creating a subscription sends future store data to its destination. Agree the recipient, event scope and permitted test data before enabling it. Use HTTPS and keep production secrets out of source code, examples and support requests.
Subscription example
This is illustrative JSON, not an instruction to register a real receiver:
{
"name": "ERP order notifications",
"url": "https://erp.example.com/webhooks/kaduno",
"events": ["order.placed", "order.confirmed"],
"secret": "REPLACE_WITH_A_RANDOM_SIGNING_SECRET"
}Replace the example address and placeholder with an approved destination and a
random secret of 16–256 characters, stored securely by the receiver. REST permits
omitting secret, but deliveries are then unsigned. Configure signing and
reject missing or invalid signatures before processing data.
Verify the exact bytes
X-Webhook-Signature contains sha256= followed by a hexadecimal HMAC-SHA256.
Calculate it over the raw request bytes, before parsing JSON. Parsing and
reserialising may change those bytes and invalidate verification.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(rawBody, signature, secret) {
if (!Buffer.isBuffer(rawBody) || typeof signature !== 'string' || !secret) {
return false;
}
const expected = Buffer.from(
'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex'),
);
const received = Buffer.from(signature);
return expected.length === received.length && timingSafeEqual(expected, received);
}Connect this verifier to your framework's raw-body support. It is not a complete HTTP receiver: request limits, durable storage, queue processing, authorisation and operational monitoring remain your responsibility. A valid signature alone is not replay protection.
Deduplicate and persist work
The body carries event, payload, deliveryId, occurredAt and timestamp.
X-Webhook-Delivery matches deliveryId, which remains the same across attempts.
Use the authenticated body's delivery identifier for your deduplication record.
- Verify the signature and validate the expected envelope and event type.
- Atomically record the delivery identifier and durable work. A unique key prevents concurrent duplicate receipts from enqueueing the same work twice.
- Return
2xxafter safe acceptance. An already accepted delivery can be acknowledged without repeating its work. - Process queued work with destination-side idempotency and reconciliation. Persisting an inbound delivery does not make an external invoice or order operation exactly once.
occurredAt describes when the event occurred; timestamp identifies the current
attempt's send time. Do not assume delivery order matches business-event order.
Check current state when your workflow requires it.
Payloads differ by event. form.submitted and quote.submitted contain identifiers,
not form answers or contact details. Retrieve required information using a
separately authorised API request and minimise what you retain or forward.
Retry and failure handling
A timeout or non-2xx response triggers retries within the configured allowance.
retryCount counts total attempts, including the first. Documented backoff starts
at 30 seconds and is capped at 10 minutes between attempts; it is not a delivery
latency or uptime guarantee.
Inspect the delivery log when attempts are exhausted. A manual retry must still pass deduplication and downstream idempotency checks. Do not delete a receipt record just to force a business action to run again. Investigate whether the first attempt already reached its destination.
Test without a live subscription
Run the local signature exercise with synthetic data. It covers a valid body, tampering and replay behaviour without API keys, a network listener or a customer order. It does not validate a real receiver's persistence, retry recovery or destination side effects.
Continue with the API quickstart and integration administration.