POST request when a subscribed event occurs.
This page covers normal event webhooks such as order:paid. For product delivery callbacks, read Dynamic product delivery.
Create a webhook
You can create a webhook in Settings → Webhooks. You can also use the Developer API.Event catalog
The event catalog contains these families:orderdisputeproductqueryfeedbackaffiliateresellersubscriptionreplacement
GET /dev/v1/webhooks/events for the current allowlist. The endpoint is the source for valid event names.
See Webhook events for payload examples. Wildcard subscriptions are not supported.
Request headers
Shoppex sends these headers with a normal event webhook:
The
v1 value inside X-Shoppex-Signature-V2 is the header format version. The header name remains X-Shoppex-Signature-V2.
Verify the V2 signature
Read the request body before you parse its JSON. Shoppex signs the exact body that it sends. Build this message:h value from X-Shoppex-Signature-V2.
Also compare the header’s t value with X-Shoppex-Timestamp. Use a constant-time function for the signature comparison.
X-Shoppex-Delivery values. If Shoppex sends the same delivery again, return success without repeating the side effect.
Legacy signatures
X-Shoppex-Signature contains an HMAC-SHA512 value for the raw body. It does not include the delivery ID or timestamp.
X-Shoppex-Unescaped-Signature is another legacy header. It signs the body after escaped slashes change from \/ to /.
New integrations must use X-Shoppex-Signature-V2.
Response and retry behavior
Shoppex treats any2xx response as success. A non-2xx response or request error starts the retry flow.
Each request has a 30-second timeout. Shoppex makes up to five delivery attempts.
The delay after a failed attempt is
2^attempts minutes. After the fifth failure, Shoppex marks the delivery as failed.
Your endpoint can receive the same event more than once. Make event processing idempotent.
Test a webhook
The test event must be part of the webhook subscription.Test webhook queued.
Rotate a secret
Rotate the secret for one webhook with this endpoint:Inspect and retry deliveries
Use these endpoints to inspect delivery results:GET /dev/v1/webhooks/logsGET /dev/v1/webhooks/logs/{id}
POST /dev/v1/webhooks/logs/{id}/retry.
Webhook events
Read event names and payload examples.
Dynamic delivery
Read the callback contract for dynamic products.