Register a URL once; from then on tracking changes for freight you booked through POST /dispatching/jobs are POSTed to it as JSON. Each delivery's details.tracking is the TrackingResult that GET /tracking/timelines/{resource_id} returns under data, with the whole timeline in one document rather than paged, so you don't need to call back to fetch the remaining movements. The event payloads are documented under Webhooks in this reference.

Every delivery carries the full current snapshot: replace your copy rather than reconstructing it from differences. A tracking.updated event carries the shipment's tracking. A documents.updated event, if you subscribe to it, carries the shipment's document collection, each file usually with a content.url download link to fetch right away, and each document with a base64_link that returns its files inline through the API.

Call POST /tracking/webhooks/{webhook_id}/test right after creating the webhook to check your endpoint receives and acknowledges a delivery.

Store the secret from the response now; it is returned only once. To verify a delivery, compute hex HMAC-SHA256 of "{X-Shipwell-Timestamp};{raw request body}" keyed with it and compare to X-Shipwell-Signature, the same scheme as Shipwell's other webhooks.

Answer with any 2xx within 10 seconds. Timeouts, network errors, 408, 429 and 5xx are retried 9 more times over about 47 hours; any other 4xx is not retried, and 410 disables the webhook. Deliveries are at least once. The same event id is sent on every retry, and sequence increases per resource_id and event: ignore an id you have seen and anything below the highest sequence you have applied for that resource_id and event_name. A documents.updated retry carries fresh download links, so match retries by id, never by body.