Skip to main content
The retailer surface delivers signed webhooks for payment, order, and refund events. Configure one endpoint per account, verify every delivery’s signature, and fetch the authoritative state with the API when an event arrives.
Webhooks fire for retailer checkouts. B2B orders have a separate, simpler legacy callback.

​
Set up your endpoint

1

Register the URL

  • The URL must be https with a public hostname — IPs, localhost, and internal hosts are rejected.
  • Omit events (or send null) to subscribe to everything.
The response includes secret (whsec_...) only on first create. Store it now — later updates return the config without it, and the only way to get a new one is rotation.
2

Verify your handler

Send a synchronous signed ping and check your endpoint’s actual response:
Response
Use this to test your signature verification end to end before going live.
3

Handle deliveries

Each delivery is a POST with a JSON envelope and three headers:Respond with any 2xx within 10 seconds. Do heavy work asynchronously — acknowledge first, process after.

​
Delivery guarantees

  • Retries: failed deliveries are retried up to 5 times with exponential backoff. A delivery that exhausts retries is marked failed in the delivery log.
  • Idempotency: retries reuse the same delivery id — deduplicate on X-Wizzgift-Delivery (also in the body as id).
  • Ordering is not guaranteed. Treat events as hints and read the authoritative state with GET /retailer/v1/checkouts/{id}.
  • Card codes are never in webhook payloads. The webhook tells you when to fetch; the authenticated GET returns the codes.

​
Per-checkout override

Pass callbackUrl on POST /retailer/v1/checkouts to route that checkout’s events to a different URL — useful for multi-tenant platforms. The override is signed with the same business secret, so a business-level endpoint must exist (it holds the secret). Without one, per-checkout URLs are ignored and you are on polling only. The endpoint’s event filter applies to overrides too.

​
Debugging deliveries

Returns recent delivery attempts with status (sent / failed), attempt counts, and a SHA-256 hash of the delivered body — enough to confirm what was sent and when without storing payloads.

​
Endpoint management