Keep your store in sync.
Configure signed testnet order notifications, inspect each attempt and recover delivery from the Webhooks dashboard. A separate configured worker is required. Actual public HTTPS receiver verification remains a release requirement.
01Create, test, activate
Verify your website in Connect website. Add an HTTPS endpoint on its exact origin, choose event subscriptions and save the signing secret once in your server secret manager. Send endpoint.test, inspect the actual response and activate after success. App passkey approval protects changes. API keys cannot manage webhook endpoints.
02Verify exact raw bytes
Use verifyWebhookSignature from the Node.js SDK before JSON parsing. Read Allwallex-Signature: t=<seconds>,v1=<hex>. HMAC-SHA256 uses the base64url-decoded 32-byte secret suffix over timestamp + dot + exact raw body. The SDK checks a 300-second clock window and a 128 KiB body limit. Match the Allwallex-Event-Id header with the authenticated body id.
03Deduplicate and check the current order
Record the authenticated event ID durably and acknowledge duplicates without repeating fulfillment. Fetch the individual order with orders:read, then bind private order ID, reference, workspace, asset, original atomic price and environment to your own stored order. A signed historical event alone cannot confirm current eligibility. endpoint.test, isTest:true, testnet and synthetic evidence never authorize a real purchase.
04Follow delivery and replay
Inspect queued, sending, retry, delivered, failed and cancelled states and the attempt timeline. Each automatic delivery has up to eight attempts within 72 hours; endpoint tests have a one-hour window. Network failures and HTTP 408, 429 and 5xx retry with bounded backoff and Retry-After. Other 4xx and redirects fail. Manual replay retains the original event ID and exact bytes, adds up to eight attempts and records your reason.
05Rotate or stop delivery
Rotation returns the endpoint to draft with a new one-time secret. Update the receiver, deliver a new test and activate again. Pause stops new order attempts; queued work waits until activation or expiry. Revoke cancels queued work permanently. An attempt already in flight can finish. Website expiry, lost manager permissions and missing retained encryption keys restrict delivery.
import { verifyWebhookSignature } from '@allwallex/checkout-sdk';
// Preserve bounded raw bytes before JSON parsing. Secret stays on your server.
verifyWebhookSignature(process.env.ALLWALLEX_WEBHOOK_SECRET!, rawBody,
request.headers['allwallex-signature']);
const event = JSON.parse(rawBody.toString('utf8'));
// Compare header Allwallex-Event-Id with event.id.
// Deduplicate event.id durably. Acknowledge endpoint.test without fulfillment.
// Fetch and bind the current authenticated order before sandbox fulfillment.
// Dashboard app-session routes; each POST requires Idempotency-Key and passkey approval:
POST /v1/workspaces/{workspaceId}/webhooks/endpoints
POST /v1/workspaces/{workspaceId}/webhooks/endpoints/{id}/test
POST /v1/workspaces/{workspaceId}/webhooks/endpoints/{id}/activate
GET /v1/workspaces/{workspaceId}/webhooks/deliveries
POST /v1/workspaces/{workspaceId}/webhooks/deliveries/{id}/replayOpen your workspace