Skip to main content
Shoppex sends an HTTP 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.
The create response contains the webhook ID and its secret. Store the secret when you create the webhook. Each webhook has its own secret. A secret for one webhook cannot verify a delivery for another webhook.

Event catalog

The event catalog contains these families:
  • order
  • dispute
  • product
  • query
  • feedback
  • affiliate
  • reseller
  • subscription
  • replacement
Use 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:
Compute its HMAC-SHA256 value with the webhook secret. Compare that value with the 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.
Do not verify a new JSON serialization of the parsed body. Whitespace or escaping changes will produce a different signature. Store processed 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 any 2xx 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.
The endpoint queues a test delivery. The response message is Test webhook queued.

Rotate a secret

Rotate the secret for one webhook with this endpoint:
The response contains the new secret. Store it immediately. The new secret replaces the previous secret for that webhook.

Inspect and retry deliveries

Use these endpoints to inspect delivery results:
  • GET /dev/v1/webhooks/logs
  • GET /dev/v1/webhooks/logs/{id}
Retry a failed delivery with POST /dev/v1/webhooks/logs/{id}/retry.

Webhook events

Read event names and payload examples.

Dynamic delivery

Read the callback contract for dynamic products.