A shipment's tracking changed.Webhook

Sent when a shipment's tracking changes: new carrier movements, a new current_state, or tracking starting or finishing. details.tracking is the full, current snapshot: the TrackingResult that GET /tracking/timelines/{resource_id} returns under data, but with the whole timeline in one document rather than paged. Replace your copy rather than reconstructing it from differences.

Delivered at least once: the same event may arrive more than once, so dedupe on id, and ignore any sequence lower than the highest you have applied.

Headers on every delivery

Header Value
Content-Type application/json; charset=utf-8
User-Agent shipwell-webhooks
X-Shipwell-Timestamp ISO-8601 time the request was signed
X-Shipwell-Signature hex HMAC-SHA256 of "{X-Shipwell-Timestamp};{raw body}", keyed with your secret

Answer with any 2xx within 10 seconds. Timeouts, network errors, 408, 429 and 5xx are retried after 30s, 2m, 10m, 30m, 1h, 3h, 6h, 12h and 24h: 10 attempts over about 47 hours. A redirect (3xx) or any other 4xx is not retried, and 410 Gone disables the webhook. Delivery is at least once: ignore an id you have already processed.

Request
header Parameters
X-Shipwell-Timestamp
required
string

ISO-8601 time the request was signed.

Example: 2026-09-26T14:05:31.123456+00:00
X-Shipwell-Signature
required
string

Hex HMAC-SHA256 of "{X-Shipwell-Timestamp};{raw body}" keyed with your webhook secret. Compare it to your own computation before trusting the body.

Request Body schema: application/json
required
id
required
string (Id)

Event id, identical on every retry: use it to ignore duplicates.

occurred_at
required
string <date-time> (Occurred At)
webhook_id
required
string (Webhook Id)

The subscription this delivery is for.

required
object (TrackingWebhookSource)
Custom Data (object) or Custom Data (null) (Custom Data)
Default: null

Echoed from the subscription.

event_name
required
string (Event Name)
Value: "tracking.updated"
sequence
required
integer (Sequence)

Strictly increasing per resource_id. Deliveries can arrive out of order; keep the highest sequence you have applied and ignore anything lower.

required
object (TrackingUpdatedDetails)
Responses
2XX

Accepted. Any 2xx stops retries.

Request samples
application/json
{
  • "id": "string",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "webhook_id": "string",
  • "source": {
    },
  • "custom_data": null,
  • "event_name": "tracking.updated",
  • "sequence": 0,
  • "details": {
    }
}
Copyright © Shipwell 2025. All right reserved.