Subscribe To Shipping Events In Real Time

Overview

Webhooks push lifecycle events to your systems so you can update storefronts, notify buyers, and keep internal tools in sync without polling.

• Signed webhook payloads
• Retry with exponential backoff
• Event catalog for labels and tracking
• Sandbox simulator where available

Authentication

Manage webhook endpoints with a Bearer token. Delivered events are signed with your endpoint secret so you can verify authenticity.

Authorization: Bearer YOUR_API_KEY

Endpoint

Create a webhook subscription with a target URL and the event types you want to receive.

curl -X POST https://api.sync-ship.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/syncship", "events": ["shipment.label_created", "shipment.tracking_updated"], "secret": "whsec_your_signing_secret"}'

Request

Provide a publicly reachable HTTPS URL, the event catalog entries to subscribe to, and an optional signing secret.

{
  "url": "https://example.com/webhooks/syncship",
  "events": ["shipment.label_created", "shipment.tracking_updated"],
  "secret": "whsec_your_signing_secret"
}

Response

Successful registration returns the webhook id and active status. Delivered payloads include event type and shipment data.

Example response

{
  "id": "wh_01HDEF",
  "url": "https://example.com/webhooks/syncship",
  "events": ["shipment.label_created", "shipment.tracking_updated"],
  "status": "active",
  "createdAt": "2026-09-09T12:00:00.000Z"
}

Errors

Standard HTTP status codes are used for management APIs. Failed deliveries are retried with backoff where configured.

• 401Missing or invalid API key.
• 422Validation failed — check URL or event names.
• 429Too many requests — retry with exponential backoff.

Next steps

Combine webhooks with Labels and Tracking APIs to close the loop from purchase to delivery updates.