Skip to main content

Receive Webhook

POST 
/webhooks/shippo/:webhook_token

The endpoint Shippo calls to deliver events for one Shippo integration instance. SKU.io registers this URL at Shippo automatically (see Webhook Subscription) — you do not call it yourself except to test. It is not under /api and takes no Bearer token: the opaque webhook_token path segment (wh_ followed by letters and digits, shown as webhook_url in Get Webhook Subscription) identifies and authenticates the instance.

Headers:

  • X-Shippo-Auth-Signature (optional): t=<unix>,v1=<hex>. When a signing secret is provisioned for the instance, the HMAC-SHA256 of "{t}.{raw body}" is verified against the raw request bytes and the timestamp must be within 5 minutes; a missing or invalid signature is rejected with 401. Without a secret the header is ignored.

Body (JSON):

  • event (string, required): transaction_created, transaction_updated or track_updated.
  • test (boolean): true for test-mode events.
  • data (object, required): for transaction events, the Shippo Transaction object; for track_updated, the Shippo Track object (carrier, tracking_number, transaction, eta, tracking_status{status, substatus, status_details, status_date, location}, tracking_history).

The event is stored (duplicate deliveries are de-duplicated) and processed in the background, so the response is immediate. Labels, tracking status, refunds and the linked fulfillment are updated from it.

Responses: 200 {received: true}; 400 for an empty body; 404 for an unknown or malformed token; 401 for a bad signature; 403 when the source IP is not one of Shippo's (only when source-IP enforcement is on); 422 when event is not a non-empty string or data is not an object.

Request​

Responses​

OK

Response Headers
    Content-Type