{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/docs/direct-carrier-connections/documents-webhooks/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Documents Webhooks

\n

Documents webhooks push a shipment's documents to your own system as the carrier produces them, so you don't have to poll. Whenever the documents of freight you booked through POST /dispatching/jobs change, Shipwell sends the shipment's full, current document collection to your URL, signed, with a download link on each file.

\n

They use the same webhook as tracking webhooks: one URL and one signing secret per company. You choose which events that webhook receives, tracking.updated, documents.updated or both.

\n

Each delivery carries the same documents and statuses that GET /documents/{resource_id} returns under data, in the webhook's own, slimmer shape: files never carry content inline, a file's content can be null, and each document adds a base64_link. Don't validate deliveries with your GET response schema; the webhook's is DocumentCollectionSummary in the API reference. Everything on the Documents page about statuses and document types applies here too.

\n

How it works

\n
CarrierShipwellYour systemCarrierShipwellYour systemOnce, at setupEvery time the documents change, with no calls from youOnly when you need itPOST /tracking/webhooks { url, event_names: [\"documents.updated\"], ... }1201 webhook id + signing secret (shown once)2POST /tracking/webhooks/{webhook_id}/test3tracking.webhook.test (signed)4BOL, delivery receipt... (Shipwell retrieves them)5documents.updated, full collection with download links (signed)62xx within 10 seconds7Download each file from content.url8GET base64_link, or GET /documents/{resource_id}9The files inline, or the collection on demand10
\n
    \n
  1. \nSubscribe, once.\n Register your URL with \ndocuments.updated\n in \nevent_names\n, or tick \nDocument updates\n on the webhook you already have.\n
    2. \n
  2. \nSend a test, once.\n The same test as for tracking proves Shipwell reaches your endpoint and your signature check passes.\n
    3. \n
  3. \nReceive updates.\n Book freight as usual. Each time its documents change, a signed \ndocuments.updated\n event arrives at your URL, usually within a minute or two.\n
    4. \n
  4. \nDownload the files.\n Each file carries a fresh download link. Fetch it as soon as the event arrives; you make no API call.\n
    5. \n
  5. \nPull when you need to.\n If a link is missing or has expired, the document's \nbase64_link\n returns its files inline. \nGET /documents/{resource_id}\n returns the current collection at any time.\n
    6. \n
\n

Before you start

\n\n

Subscribe

\n

In the Shipwell app

\n

Open Company → Webhooks. In the Tracking section, choose Edit on your webhook, or Set up tracking webhook if you don't have one yet. Under Events, tick Document updates, alongside Tracking updates or on its own, then save. At least one event must stay ticked.

\n

The webhook's details then list both events, and Delivery history shows which event each delivery carried in its Event column.

\n

Through the REST API

\n

Include documents.updated in event_names when you register your URL. Everything else about registering a URL is unchanged.

\n
\n Example request\n
\n
' \\\\\n--header 'Content-Type: application/json' \\\\\n--data-raw '{\n "url": "https://tms.example.com/hooks/shipwell",\n "event_names": ["tracking.updated", "documents.updated"],\n "error_contact_email": "integrations@example.com",\n "custom_data": { "tms": "acme-prod" }\n}'`, `38248683362691160000`)\"\n >\n
Copy
\n
Copied
\n
\n 
curl --request POST 'https://sandbox-api.shipwell.com/tracking/webhooks' \\\n--header 'Authorization: Token <user-token>' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n  "url": "https://tms.example.com/hooks/shipwell",\n  "event_names": ["tracking.updated", "documents.updated"],\n  "error_contact_email": "integrations@example.com",\n  "custom_data": { "tms": "acme-prod" }\n}'
\n
\n
\n

The response is the same as for tracking, with \"event_names\": [\"tracking.updated\", \"documents.updated\"]. Store the secret now: it is returned only once.

\n

A company has one webhook, so registering again answers 409. To add documents to a webhook you already registered, use the app.

\n

Receive documents.updated

\n

Shipwell sends documents.updated whenever the shipment's document collection changes:

\n\n

If a check with the carrier changes nothing, nothing is sent. The headers and signature are exactly those of tracking deliveries.

\n
\n Example documents.updated (abridged to one document)\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"id\": \"01KC3B9R2T4V6X8Z0A2C4E6G8J\",\n  \"event_name\": \"documents.updated\",\n  \"occurred_at\": \"2026-08-23T17:05:00.031882+00:00\",\n  \"webhook_id\": \"01KC2W7HQ3M8R5T6V9X0YZABCD\",\n  \"source\": {\n    \"publishing_system\": \"genesis\",\n    \"company_id\": \"3b1f6c2e-8a4d-4f7b-9c21-5e7d0a9b4c11\",\n    \"environment\": \"sandbox\"\n  },\n  \"custom_data\": { \"tms\": \"acme-prod\" },\n  \"sequence\": 3,\n  \"details\": {\n    \"resource_id\": \"9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e\",\n    \"documents\": {\n      \"resource_id\": \"9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e\",\n      \"resource_type\": \"document_collection\",\n      \"self_link\": \"https://sandbox-api.shipwell.com/documents/9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e\",\n      \"status\": \"COMPLETED\",\n      \"is_terminal\": true,\n      \"documents\": [\n        {\n          \"id\": \"01KBZD1P4M0000000000000000\",\n          \"resource_type\": \"document\",\n          \"document_type\": \"BOL\",\n          \"name\": \"Bill of Lading\",\n          \"status\": \"COMPLETED\",\n          \"completed_at\": \"2026-08-23T17:04:18.220Z\",\n          \"self_link\": \"https://sandbox-api.shipwell.com/documents/9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e/BOL\",\n          \"base64_link\": \"https://sandbox-api.shipwell.com/documents/9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e/BOL?encoding=base64\",\n          \"files\": [\n            {\n              \"id\": \"01KBZD1P4N0000000000000000\",\n              \"format\": \"PDF\",\n              \"filename\": \"bol-77120.pdf\",\n              \"size_in_bytes\": 184223,\n              \"content\": {\n                \"url\": { \"value\": \"https://documents.example.com/bol-77120.pdf?X-Amz-Expires=600&X-Amz-Signature=...\" },\n                \"base64\": null\n              }\n            }\n          ]\n        }\n      ],\n      \"errors\": []\n    }\n  }\n}
\n
\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldMeaning
id, occurred_at, webhook_id, source, custom_dataAs for tracking.updated.
event_namedocuments.updated.
sequenceIncreases for each resource_id, counted separately from tracking.updated. A shipment's tracking and documents each have their own sequence.
details.documentsThe full collection, with every document so far rather than only the new ones. Same documents and statuses as GET /documents/{resource_id}, in the webhook's shape (DocumentCollectionSummary).
documents[].self_linkThe document's own endpoint, GET /documents/{resource_id}/{document_type}.
documents[].base64_linkThe same endpoint with ?encoding=base64. Call it with your API key to get the files inline. It returns every document of that type, so pick the one whose id matches.
files[].content.url.valueA download link set when this delivery was sent. See Download the files.
files[].contentnull when Shipwell has no link for the file, for example a file it holds only inline. Use base64_link.
\n

Download the files

\n

The webhook never carries file content, so its size stays small whatever the documents weigh. Each file carries a link instead:

\n\n

Download each file as soon as the event arrives, before you do anything slower. A retry of the same event is sent with fresh links.

\n

If a file has content: null, or its link has expired or fails, call the document's base64_link with your API key. It returns the files inline as base64 for every document of that document_type, so a shipment with two BOLs returns both: pick the document whose id matches, and call the link once per type rather than once per document. A file over 50 MB comes back with too_large_for_inline: true and a link instead. See Documents for the response.

\n

Handle each delivery

\n

Use the same four rules as for tracking deliveries: ignore an id you have already processed; keep the highest sequence per resource_id and event_name and ignore anything lower; replace your copy of the collection rather than merging; store, acknowledge, then process.

\n

Two things are specific to documents:

\n\n

GET /documents/{resource_id} carries no sequence, so it can't be ordered against deliveries: a delivery that was being retried while you pulled may hold an older collection than the one you pulled. Use the pull to fill gaps, such as catching up after downtime, keep applying deliveries by sequence, and pull that shipment again after applying any delivery that arrives after a pull. A retry can arrive hours later.

\n

Retries, pausing and delivery history

\n

These work as for tracking webhooks, because it is the same webhook: see Retries and Pause, change or remove a webhook. Pausing the webhook pauses both events.

\n

One difference: a retry of a documents.updated event keeps its id and sequence, but its file links are made fresh for that attempt, so the body changes. Recognise a retry by its id, never by comparing bodies, and always download from the links in the attempt you received, not from an earlier one.

\n

Errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
StatuscodeMeaning
403documents_webhooks_not_enabledevent_names includes documents.updated, and documents webhooks aren't enabled for your company yet. Contact your Shipwell representative, or leave it out of event_names.
403webhooks_not_enabledTracking webhooks, which documents webhooks ride on, aren't enabled for your company yet.
\n

Every other error is as listed for tracking webhooks.

\n

Troubleshooting

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SymptomCheck
Tracking arrives but no documents.updatedThat the webhook's events include documents.updated (the details in Company → Webhooks list them), and that the shipment's documents have changed since you subscribed. GET /documents/{resource_id} shows the current collection.
A download link answers 403 or AccessDeniedIt has expired. Shipwell links last about 10 minutes, so download on receipt, or call the document's base64_link.
A file has content: nullShipwell holds that file without a link. Call the document's base64_link.
Documents look older than what you already haveYou applied a lower sequence, or compared against the tracking sequence. Keep the highest sequence per resource_id and event_name.
\n

API reference

\n

Tracking Webhooks API reference: the documents.updated payload with every field, under Webhooks.

\n

Next steps

\n

Read Documents for what the collection's fields and statuses mean, and Tracking Webhooks for verifying signatures, with Node.js and Python examples.

","headings":[{"value":"Documents Webhooks","depth":1},{"value":"How it works","depth":2},{"value":"Before you start","depth":2},{"value":"Subscribe","depth":2},{"value":"In the Shipwell app","depth":3},{"value":"Through the REST API","depth":3},{"value":"Receive documents.updated","depth":2},{"value":"Download the files","depth":2},{"value":"Handle each delivery","depth":2},{"value":"Retries, pausing and delivery history","depth":2},{"value":"Errors","depth":2},{"value":"Troubleshooting","depth":2},{"value":"API reference","depth":2},{"value":"Next steps","depth":2}]},"contentItem":{"data":{"lastModified":"2026-10-03T23:48:23.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":true,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"f7f3335e-a14c-53d7-9c56-a02229323b3e__redocly content/docs/direct-carrier-connections/documents-webhooks/","seo":{"title":"Documents Webhooks","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/direct-carrier-connections/documents-webhooks.md","pageBaseUrl":"/docs/direct-carrier-connections/documents-webhooks","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Documents Webhooks","id":"documents-webhooks"},{"depth":2,"value":"How it works","id":"how-it-works"},{"depth":2,"value":"Before you start","id":"before-you-start"},{"depth":2,"value":"Subscribe","id":"subscribe"},{"depth":3,"value":"In the Shipwell app","id":"in-the-shipwell-app"},{"depth":3,"value":"Through the REST API","id":"through-the-rest-api"},{"depth":2,"value":"Receive documents.updated","id":"receive-documentsupdated"},{"depth":2,"value":"Download the files","id":"download-the-files"},{"depth":2,"value":"Handle each delivery","id":"handle-each-delivery"},{"depth":2,"value":"Retries, pausing and delivery history","id":"retries-pausing-and-delivery-history"},{"depth":2,"value":"Errors","id":"errors"},{"depth":2,"value":"Troubleshooting","id":"troubleshooting"},{"depth":2,"value":"API reference","id":"api-reference"},{"depth":2,"value":"Next steps","id":"next-steps"}]},"data":{"title":"Documents Webhooks"},"catalogInfo":null,"link":"/docs/direct-carrier-connections/documents-webhooks/","sidebarName":"developerPortal","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}