Skip to main content
A callback receives the deliveries of the API version it was registered through. Callbacks registered with POST /api/v1/orders keep receiving v1 deliveries; callbacks registered with POST /api/v2/orders receive v2 events. Nothing changes for a callback until you register it through v2.

​
What changes

Everything else is the same in both versions: the callback object you send, the authentication options, the request headers, the outbound IP addresses, and the retry policy.

​
Fetch the order for its state

A v2 event names the order and carries no status:
data.url is a path relative to the API origin. Fetch it with an API token that has the order.read scope:
The response is the order in the v2 format, not the v1 body — see Get an order for its fields and Order lifecycle for its statuses. Act on the state you fetch, not on the number or order of events: see Duplicates and ordering.

​
Verify the v2 signature

The v2 X-Signature header adds the send time: t=<unix seconds>,sha256=<hex>, where sha256 is the HMAC-SHA256 of t, a ., and the raw body, keyed with the same callback.auth.secretKey. Reject a delivery whose t is more than 5 minutes old. Verify the signature has the steps and sample code. A v1 signature stays sha256=<hex>, the HMAC-SHA256 of the raw body alone. Both versions sign the exact bytes sent, so verify against the body as received.

​
Switch a callback to v2

  1. Accept both versions. Deliveries queued before the switch keep their v1 body and signature, so your endpoint receives both for a while. Choose the verification by the X-Signature format (a value starting with t= is v2), then branch on the body’s object: "event" is v2, "order" is v1.
  2. Register through v2. For a new order, send the callback with POST /api/v2/orders. An existing order’s callback moves to v2 when POST /api/v2/orders returns that order (200 OK with a matched block) and the request’s callback.url is the one already registered. Send the whole callback, auth and headers included: any the request omits are removed. See Register a callback again.
  3. Keep accepting v1 until queued deliveries drain. An event keeps the version it was created with on every retry, so v1 deliveries can arrive for up to about an hour after the switch.
Registering a different url through v2 adds a second registration instead of moving the first: the old URL keeps receiving v1 deliveries. To stop v1 deliveries to a URL, register that same URL through v2.