Endpoint & authentication

• Your endpoint must be HTTPS. Respond 2xx to acknowledge; other responses (or timeouts) are retried, then marked failed and re-sendable from the Deliveries page.
• Signing secret (recommended): set a secret and verify the HMAC signature below.
• HTTP Basic auth: leave the secret blank and embed credentials in the URL (https://user:pass@host); we store them encrypted and send them via the Authorization header (no signature header in that case).

Headers & signature

The signature is v1= followed by a lowercase hex HMAC-SHA256(secret, "<timestamp>.<raw_body>"). Reject deliveries whose x-webhook-timestamp is too far from now to prevent replays.

POST /your/webhook/endpoint HTTP/1.1
content-type: application/json
x-webhook-timestamp: 1718712000
x-webhook-signature: v1=3f9a...  (hex HMAC-SHA256)

Verifying (Node.js)

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const ts = headers["x-webhook-timestamp"];
  const sig = headers["x-webhook-signature"]; // "v1=<hex>"
  const expected =
    "v1=" + crypto.createHmac("sha256", secret)
                  .update(ts + "." + rawBody)
                  .digest("hex");
  // reject if Math.abs(Date.now()/1000 - Number(ts)) > 300
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Example payload

One event per order-item status change. status_change_id is a stable idempotency key, so dedupe on it. Some fields may be null.

{
  "event": "order_item.status_changed",
  "status_change_id": "9f8c1a2b-4d5e-6f70-8192-a3b4c5d6e7f8",
  "environment": "production",
  "order_number": "abc-123",
  "external_order_id": "your-ref-1",
  "external_user_id": "user-42",
  "line_item_id": "li-1",
  "status": "exported",
  "occurred_at": "2026-06-18T12:00:00Z"
}

Status values

status is one of new, pending, exported, fulfilled, cancelled, backordered, rejected. You choose which fire per environment on the Webhooks settings page; selecting none means no webhooks are sent.