How webhooks work

Instead of asking the API what changed, you give us a URL and we POST an event to you the moment something happens. A shipment status change, a completed refund, a payment failure: each arrives at your endpoint within seconds.

Subscribe to events

  1. Open My applications and select your application.
  2. Choose the events you want to receive, such as order.shipped or payment.failed.
  3. Add the HTTPS endpoint that should receive them.

Your endpoint must:

  • Be reachable over HTTPS with a valid certificate.
  • Respond with a 2xx status within five seconds.
  • Handle events out of order. Delivery retries mean events can arrive twice or late.

Verify every event

Each delivery includes a signature header so you know it came from us and was not tampered with:

X-Signature: t=1727712000,v1=5f8a3c...

Verify it with your webhook signing secret, found on your application page:

import { createHmac, timingSafeEqual } from 'crypto'

function verifySignature(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== 'string') return false
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(part => part.split('='))
  )
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex')
  const received = Buffer.from(parts.v1 ?? '')
  return received.length === expected.length && timingSafeEqual(Buffer.from(expected), received)
}

Verify the raw request body, before any JSON parsing. If verification fails, reject the request.

The event payload

{
  "id": "evt_3f8d2a",
  "type": "order.shipped",
  "created_at": "2024-10-01T12:00:00Z",
  "data": {
    "order_id": "ord_1042",
    "status": "shipped"
  }
}

Handle failures

We retry failed deliveries with exponential backoff for 24 hours. If your endpoint keeps failing, the subscription is paused and you'll get an email. Process events idempotently by their id, so a redelivery never causes a duplicate action.

Next steps