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

Tracking Webhooks

\n

Tracking webhooks push tracking changes to your own system as they happen, so you don't have to poll. Register your URL once. From then on, whenever the tracking of freight you booked through POST /dispatching/jobs changes, Shipwell sends the shipment's full, current tracking to that URL, signed so you can prove it came from Shipwell.

\n

Each delivery carries the same tracking that GET /tracking/timelines/{resource_id} returns under data, with the whole timeline in one document instead of paged. Everything on the Tracking page about reading it applies here too.

\n

How it works

\n
CarrierShipwellYour systemCarrierShipwellYour systemOnce, at setupEvery time tracking changes, with no calls from youOnly when you need itPOST /tracking/webhooks { url, error_contact_email }1201 webhook id + signing secret (shown once)2POST /tracking/webhooks/{webhook_id}/test3tracking.webhook.test (signed)4200 { delivered, response_code, latency_ms }5New movement (Shipwell polls the carrier)6tracking.updated, full snapshot (signed)72xx within 10 seconds8GET /tracking/timelines/{resource_id}9The same snapshot, on demand10
\n
    \n
  1. \nRegister your URL, once.\n Shipwell returns a signing \nsecret\n. Store it: it is shown only this once.\n
    2. \n
  2. \nSend a test, once.\n Shipwell sends a signed test event to your URL right away and tells you what your endpoint answered. A \n2xx\n proves Shipwell reached your endpoint through your firewall and TLS. Make your handler reject a bad signature, so a \n2xx\n also means your signature check passed.\n
    3. \n
  3. \nReceive updates.\n Book freight as usual. Each time its tracking changes, a signed \ntracking.updated\n event arrives at your URL, usually within a minute or two. You make no calls.\n
    4. \n
  4. \nPull when you need to.\n After downtime, or for a periodic reconcile, read the same tracking with \nGET /tracking/timelines/{resource_id}\n. See \nMixing pull and push\n.\n
    5. \n
\n

Before you start

\n\n

Two ways to set it up

\n

You can manage your tracking webhook in the Shipwell app, with no code, or from your own system through the REST API. Use whichever suits your team; both work on the same webhook.

\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
In the Shipwell appThrough the REST API
Register your URLYesYes, POST /tracking/webhooks
Get the signing secret, onceYesYes, in the create response
Send a test deliveryYesYes, POST /tracking/webhooks/{webhook_id}/test
Edit, pause, resume or deleteYesNot available yet; use the app
Delivery history and retryYesNot available yet; use the app
\n

Start with Set it up in the Shipwell app or Step 1: Register your URL for the API. Receiving and verifying deliveries is the same either way: see Step 3 and Verify every delivery.

\n

Set it up in the Shipwell app

\n

Open Company → Webhooks. If you sign in with the API integration user, it sits next to API Keys. Company administrators find it under Developer Tools → Carrier Connection Webhooks.

\n
    \n
  1. \nIn the \nTracking\n section, choose \nSet up tracking webhook\n, enter your HTTPS URL and an error contact email, choose the \nEvents\n to receive (\nTracking updates\n, and \nDocument updates\n if \ndocuments webhooks\n are enabled for your company), optionally add custom data, then choose \nCreate webhook\n.\n
    2. \n
  2. \nCopy the signing secret. It is shown only this once, and \nDone\n stays disabled until you confirm you've stored it.\n

    \"The

    \n
    3. \n
  3. \nChoose \nSend test delivery\n. Shipwell sends a signed test event to your URL and shows whether it was delivered, your endpoint's response code and how long it took.\n

    \"The

    \n
    4. \n
  4. \nFrom the same section you can \nEdit\n the URL, events, error contact or custom data, \nPause\n and resume deliveries, or \nDelete\n the webhook.\n
    5. \n
  5. \nDelivery history\n lists the last 30 days of deliveries, newest first, with each one's event, status, attempts and your endpoint's last answer. Filter to \nFailed\n and choose \nRetry\n on a delivery, or \nRetry all failed\n after an outage on your side. A retried delivery goes out within about a minute with its original event \nid\n, so your duplicate check still works.\n

    \"Delivery

    \n
    6. \n
\n

Endpoints

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointWhat it does
POST /tracking/webhooksRegister a URL. Returns the webhook id and its signing secret.
POST /tracking/webhooks/{webhook_id}/testSend one signed test event now and see what your endpoint answered.
\n

The events Shipwell sends, tracking.updated, documents.updated and tracking.webhook.test, are described under Webhooks in the API reference. This page covers tracking; Documents Webhooks covers documents on the same webhook.

\n

Step 1: Register your URL

\n

The steps from here use the REST API. To do the same in the app, see Set it up in the Shipwell app.

\n

A company has one tracking webhook. Registering a second answers 409 with webhook_already_exists.

\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
FieldRequiredNotes
urlYesHTTPS only, resolving to a public address. Up to 2,048 characters, with no username or password in it.
error_contact_emailYesWho Shipwell contacts if deliveries to your URL keep failing.
custom_dataNoAny JSON object up to 4 KB. It comes back as custom_data in every delivery, which is handy for routing, such as your system's environment or tenant.
event_namesNoDefaults to [\"tracking.updated\"]. Add \"documents.updated\" to receive document changes on the same URL too; see Documents Webhooks.
\n
\n Example request\n
\n
' \\\\\n--header 'Content-Type: application/json' \\\\\n--data-raw '{\n "url": "https://tms.example.com/hooks/shipwell-tracking",\n "error_contact_email": "integrations@example.com",\n "custom_data": { "tms": "acme-prod" }\n}'`, `99192935601693750000`)\"\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-tracking",\n  "error_contact_email": "integrations@example.com",\n  "custom_data": { "tms": "acme-prod" }\n}'
\n
\n
\n
\n Example response (201)\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"data\": {\n    \"id\": \"01KC2W7HQ3M8R5T6V9X0YZABCD\",\n    \"resource_type\": \"tracking_webhook\",\n    \"self_link\": \"https://sandbox-api.shipwell.com/tracking/webhooks/01KC2W7HQ3M8R5T6V9X0YZABCD\",\n    \"url\": \"https://tms.example.com/hooks/shipwell-tracking\",\n    \"event_names\": [\"tracking.updated\"],\n    \"status\": \"ENABLED\",\n    \"error_contact_email\": \"integrations@example.com\",\n    \"custom_data\": { \"tms\": \"acme-prod\" },\n    \"created_at\": \"2026-08-19T15:12:08.102181Z\",\n    \"updated_at\": \"2026-08-19T15:12:08.102181Z\",\n    \"secret\": \"whsec_EXAMPLE_DO_NOT_USE\"\n  }\n}
\n
\n
\n

Store the secret now. It is returned only in this response, and you need it to verify every delivery. Keep it where you keep other credentials, never in client-side code or logs.

\n

Step 2: Send a test

\n

Call this right after registering. Shipwell sends one signed tracking.webhook.test event to your URL and answers with what your endpoint did.

\n
\n Example request\n
\n
'`, `7362823156660147000`)\"\n >\n
Copy
\n
Copied
\n
\n 
curl --request POST 'https://sandbox-api.shipwell.com/tracking/webhooks/01KC2W7HQ3M8R5T6V9X0YZABCD/test' \\\n--header 'Authorization: Token <user-token>'
\n
\n
\n
\n Example response (200)\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"data\": {\n    \"delivered\": true,\n    \"response_code\": 200,\n    \"error\": null,\n    \"latency_ms\": 412.6\n  }\n}
\n
\n
\n

The response is 200 whether or not your endpoint accepted the test, so read delivered:

\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
deliveredresponse_codeWhat to check
true2xxNothing. You're ready.
false4xx or 5xxYour endpoint answered but refused. Often a signature check failing, or a route or method mismatch: the test is a POST.
falsenullShipwell couldn't reach your endpoint. error says why: a timeout, a TLS problem, a name that doesn't resolve, or an address that isn't public.
\n

Shipwell can't see whether your endpoint verified the signature, only what it answered. Make your handler reject a bad signature with a 4xx, so delivered: true also means your check passed.

\n

A test is sent once and never retried or stored. Its body looks like any delivery, with event_name: \"tracking.webhook.test\", sequence: 0 and a short message in details.

\n

Step 3: Receive tracking.updated

\n

Book freight with POST /dispatching/jobs as usual. Shipwell sends tracking.updated whenever that shipment's tracking changes:

\n\n

If a check with the carrier changes nothing, nothing is sent. Several movements reported at once arrive as one event carrying all of them.

\n

Headers

\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
HeaderValue
X-Shipwell-SignatureHex HMAC-SHA256 of {X-Shipwell-Timestamp};{raw request body}, keyed with your webhook's secret.
X-Shipwell-TimestampWhen this attempt was signed, as ISO 8601, for example 2026-08-23T17:03:00.064978+00:00. A new value on every retry.
Content-Typeapplication/json; charset=utf-8
User-Agentshipwell-webhooks
\n
\n Example tracking.updated (abridged to two movements)\n
\n
\n
Copy
\n
Copied
\n
\n 
{\n  \"id\": \"01KC2WA3F5G6H7J8K9M0N1P2Q3\",\n  \"event_name\": \"tracking.updated\",\n  \"occurred_at\": \"2026-08-23T17:03:00.053997+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\": 2,\n  \"details\": {\n    \"resource_id\": \"9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e\",\n    \"tracking\": {\n      \"resource_id\": \"9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e\",\n      \"resource_type\": \"tracking\",\n      \"self_link\": \"https://sandbox-api.shipwell.com/tracking/timelines/9f2c1b84-6d3a-4c17-9b0e-2f5a7c48d31e\",\n      \"tracking_status\": \"COMPLETED\",\n      \"is_terminal\": true,\n      \"current_state\": \"DELIVERED\",\n      \"current_state_at\": \"2026-08-23T16:40:00Z\",\n      \"provider_code\": \"RLC\",\n      \"carrier_name\": \"R+L Carriers\",\n      \"carrier_scac\": \"RLCA\",\n      \"tracking_reference_kind\": \"PRO_NUMBER\",\n      \"tracking_reference\": \"123456789\",\n      \"events\": [\n        {\n          \"id\": \"01KBZD4Q6W0000000000000001\",\n          \"occurred_at\": \"2026-08-20T14:05:00Z\",\n          \"recorded_at\": \"2026-08-20T14:31:02.118Z\",\n          \"description\": \"Shipment picked up\",\n          \"carrier_status_code\": \"PKP\",\n          \"shipment_state\": \"AT_PICKUP\",\n          \"provider_code\": \"RLC\",\n          \"location\": { \"city\": \"CHARLOTTE\", \"state\": \"NC\", \"postal_code\": \"28202\", \"country\": \"US\" },\n          \"latitude\": 35.22709,\n          \"longitude\": -80.84313\n        },\n        {\n          \"id\": \"01KBZD4Q6W0000000000000009\",\n          \"occurred_at\": \"2026-08-23T16:40:00Z\",\n          \"recorded_at\": \"2026-08-23T17:02:41.550Z\",\n          \"description\": \"Delivered\",\n          \"carrier_status_code\": \"DEL\",\n          \"shipment_state\": \"DELIVERED\",\n          \"provider_code\": \"RLC\",\n          \"location\": { \"city\": \"RALEIGH\", \"state\": \"NC\", \"postal_code\": \"27601\", \"country\": \"US\" },\n          \"latitude\": 35.77959,\n          \"longitude\": -78.63818\n        }\n      ],\n      \"next_cursor\": null\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\n\n\n\n
FieldMeaning
idThis event's id. The same on every retry of it, so use it to spot duplicates.
event_nametracking.updated, or tracking.webhook.test for a test.
occurred_atWhen Shipwell created the event. Carrier times are on each movement.
webhook_idWhich of your webhooks this delivery is for.
sourceWho sent it. company_id is your company, and environment tells sandbox from production.
custom_dataExactly what you registered, echoed back.
sequenceIncreases for each resource_id. It never goes backwards, and it can skip numbers.
details.resource_idThe shipment, as returned by the dispatch.
details.trackingThe full tracking, the same TrackingResult that GET /tracking/timelines/{resource_id} returns under data. Every movement so far is included in this one document, not paged and not only the new ones, so next_cursor is always null.
\n

Verify every delivery

\n

Before trusting a delivery, check its signature:

\n
    \n
  1. \nTake the \nraw request body\n, exactly as received. Don't parse and re-serialize it first: a single changed space breaks the signature.\n
    2. \n
  2. \nBuild the string \n{X-Shipwell-Timestamp};{raw body}\n.\n
    3. \n
  3. \nCompute HMAC-SHA256 of it, keyed with your webhook's \nsecret\n, as lowercase hex.\n
    4. \n
  4. \nCompare it with \nX-Shipwell-Signature\n in constant time. If they differ, answer \n401\n and ignore the delivery.\n
    5. \n
\n

To guard against replays, also reject a delivery whose X-Shipwell-Timestamp is more than a few minutes old. Retries are signed afresh, so a genuine retry always passes this check.

\n
\n Node.js (Express)\n
\n
{\n const timestamp = req.get("X-Shipwell-Timestamp") || "";\n const received = req.get("X-Shipwell-Signature") || "";\n const expected = crypto\n .createHmac("sha256", SECRET)\n .update(\\\\`redocly_dollar_sign{timestamp};redocly_dollar_sign{req.body.toString("utf8")}\\\\`)\n .digest("hex");\n\n const valid =\n received.length === expected.length &&\n crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));\n const fresh = Math.abs(Date.now() - Date.parse(timestamp)) < 5 * 60 * 1000;\n if (!valid || !fresh) return res.sendStatus(401);\n\n const event = JSON.parse(req.body);\n try {\n await storeDurably(event); // your queue or database: resolve only once the event is persisted\n } catch (err) {\n return res.sendStatus(503); // not stored, so let Shipwell retry\n }\n res.sendStatus(204); // acknowledge after storing, process afterwards\n});`, `82318355385735580000`)\"\n >\n
Copy
\n
Copied
\n
\n 
const crypto = require(\"crypto\");\nconst express = require(\"express\");\n\nconst app = express();\nconst SECRET = process.env.SHIPWELL_WEBHOOK_SECRET; // the whsec_... value from registration\n\n// express.raw keeps the body as the exact bytes Shipwell signed.\napp.post(\"/hooks/shipwell-tracking\", express.raw({ type: \"application/json\" }), async (req, res) => {\n  const timestamp = req.get(\"X-Shipwell-Timestamp\") || \"\";\n  const received = req.get(\"X-Shipwell-Signature\") || \"\";\n  const expected = crypto\n    .createHmac(\"sha256\", SECRET)\n    .update(`${timestamp};${req.body.toString(\"utf8\")}`)\n    .digest(\"hex\");\n\n  const valid =\n    received.length === expected.length &&\n    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));\n  const fresh = Math.abs(Date.now() - Date.parse(timestamp)) < 5 * 60 * 1000;\n  if (!valid || !fresh) return res.sendStatus(401);\n\n  const event = JSON.parse(req.body);\n  try {\n    await storeDurably(event); // your queue or database: resolve only once the event is persisted\n  } catch (err) {\n    return res.sendStatus(503); // not stored, so let Shipwell retry\n  }\n  res.sendStatus(204); // acknowledge after storing, process afterwards\n});
\n
\n
\n
\n Python (Flask)\n
\n
timedelta(minutes=5):\n abort(401)\n\n try:\n store_durably(request.get_json()) # your queue or database: return only once persisted\n except Exception:\n abort(503) # not stored, so let Shipwell retry\n return "", 204 # acknowledge after storing, process afterwards`, `68598550912833446000`)\"\n >\n
Copy
\n
Copied
\n
\n 
import hashlib\nimport hmac\nimport os\nfrom datetime import datetime, timedelta, timezone\n\nfrom flask import Flask, abort, request\n\napp = Flask(__name__)\nSECRET = os.environ[\"SHIPWELL_WEBHOOK_SECRET\"]  # the whsec_... value from registration\n\n\n@app.post(\"/hooks/shipwell-tracking\")\ndef shipwell_tracking():\n    timestamp = request.headers.get(\"X-Shipwell-Timestamp\", \"\")\n    received = request.headers.get(\"X-Shipwell-Signature\", \"\")\n    body = request.get_data(as_text=True)  # the raw body, exactly as sent\n    expected = hmac.new(SECRET.encode(), f\"{timestamp};{body}\".encode(), hashlib.sha256).hexdigest()\n\n    if not hmac.compare_digest(received, expected):\n        abort(401)\n    try:\n        sent_at = datetime.fromisoformat(timestamp)\n    except ValueError:\n        abort(401)\n    if abs(datetime.now(timezone.utc) - sent_at) > timedelta(minutes=5):\n        abort(401)\n\n    try:\n        store_durably(request.get_json())  # your queue or database: return only once persisted\n    except Exception:\n        abort(503)  # not stored, so let Shipwell retry\n    return \"\", 204  # acknowledge after storing, process afterwards
\n
\n
\n

This is the same signing scheme as Shipwell's platform webhooks, so code you already use to verify those works here unchanged.

\n

Handle each delivery

\n

Deliveries are at least once, and they aren't guaranteed to arrive in order. Four rules make that safe:

\n
    \n
  1. \nIgnore an id you have already processed.\n A retry after a timeout, or a response Shipwell never saw, sends the same event again.\n
    2. \n
  2. \nKeep the highest sequence per resource_id, and ignore anything lower.\n An older snapshot arriving late must not overwrite a newer one. If your webhook also receives \ndocuments.updated\n, keep it per \nresource_id\n and \nevent_name\n: each event counts its own sequence.\n
    3. \n
  3. \nReplace, don't merge.\n \ndetails.tracking\n is the whole current state, so overwrite your copy of the shipment's tracking with it. There's nothing to reconstruct from differences.\n
    4. \n
  4. \nStore, acknowledge, then process.\n Answer \n2xx\n only once the delivery is verified and stored durably, then do the rest of the work. If you can't store it, answer \n503\n and Shipwell retries. A \n2xx\n for an event you then lose can't be recovered by retry.\n
    5. \n
\n

sequence can skip numbers, so never wait for a missing one. A gap simply means a snapshot you had no webhook to receive.

\n

Mixing pull and push

\n

GET /tracking/timelines/{resource_id} returns the current tracking but carries no sequence, so it can't be ordered against deliveries. A delivery that was being retried while you pulled may hold an older snapshot than the one you pulled, and no later change is guaranteed to correct it. So:

\n\n

Retries

\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
Your endpoint answersWhat Shipwell does
Any 2xxDone.
A timeout (over 10 seconds), a network or TLS error, 408, 429 or 5xxRetries after 30 seconds, then 2 minutes, 10 minutes, 30 minutes, 1 hour, 3, 6, 12 and 24 hours: 10 attempts over about 47 hours. A Retry-After header on a 429 or 503 is honoured.
410 GoneStops, and disables the webhook. Use it when you've retired the URL.
Any other 4xx, or a 3xxStops, without retrying: a refusal won't change on its own. Redirects are not followed.
\n

Every retry of an event carries the same id and body, with a new X-Shipwell-Timestamp and signature. The one exception is documents.updated, whose file download links are made fresh for each attempt; see Documents Webhooks. To send a failed delivery again yourself, use Retry in Delivery history. If an event exhausts its retries, the next change to that shipment still sends the full, current snapshot, and GET /tracking/timelines/{resource_id} always has it.

\n

Pause, change or remove a webhook

\n

Use Edit, Pause and Delete in the Tracking section of Company → Webhooks in the Shipwell app. Pausing stops deliveries until you resume; a delivery can't be retried while its webhook is paused. To stop deliveries from your side at once, answer 410 Gone: Shipwell disables the webhook on the first one, and you can resume it in the app.

\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\n\n\n\n
StatuscodeMeaning
400The request body is invalid, for example a URL that isn't HTTPS, points at a private address, or contains whitespace. errors[].source.pointer names the field.
401The Authorization header is missing or invalid. Send Authorization: Token <user-token>.
403webhooks_not_enabledTracking webhooks aren't enabled for your company yet. Contact your Shipwell representative.
403documents_webhooks_not_enabledevent_names includes documents.updated, which isn't enabled for your company yet. See Documents Webhooks.
409webhook_already_existsYour company already has a tracking webhook. Change its URL instead of registering another.
404webhook_not_foundNo webhook with that id for your company. Another company's webhook answers the same as one that doesn't exist.
429Too many requests. Wait a moment and try again.
503webhooks_unavailableTracking webhooks aren't available in this environment yet.
\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\n\n\n\n
SymptomCheck
The test says delivered: false with response_code: nullThat your URL is reachable from the internet over HTTPS with a valid certificate, and resolves to a public address.
The test reaches you, but your signature check failsThat you hash the raw body, not a parsed and re-serialized copy, and use the secret from this webhook's registration.
The test works, but no tracking.updated arrivesThat the freight was booked through POST /dispatching/jobs by the same company, and that its tracking has changed since you registered. Changes before registration aren't sent. GET /tracking/timelines/{resource_id} shows the current state.
The same event arrives twiceExpected with at-least-once delivery. Skip an id you've already processed.
Deliveries stoppedDelivery history in the app: failed deliveries show your endpoint's last answer. Check the webhook isn't paused; a 410 Gone answer pauses it. Fix your endpoint, then Retry all failed.
\n

API reference

\n

Tracking Webhooks API reference: both endpoints and both event payloads, with every field.

\n

Next steps

\n

Read Tracking for what the tracking document's fields and states mean, and have the shipment's documents pushed to the same webhook or pull them as it nears delivery.

","headings":[{"value":"Tracking Webhooks","depth":1},{"value":"How it works","depth":2},{"value":"Before you start","depth":2},{"value":"Two ways to set it up","depth":2},{"value":"Set it up in the Shipwell app","depth":2},{"value":"Endpoints","depth":2},{"value":"Step 1: Register your URL","depth":2},{"value":"Step 2: Send a test","depth":2},{"value":"Step 3: Receive tracking.updated","depth":2},{"value":"Headers","depth":3},{"value":"Verify every delivery","depth":2},{"value":"Handle each delivery","depth":2},{"value":"Mixing pull and push","depth":3},{"value":"Retries","depth":2},{"value":"Pause, change or remove a webhook","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":"e2362791-d2ac-5d1c-bfc4-fa5634802c8d__redocly content/docs/direct-carrier-connections/tracking-webhooks/","seo":{"title":"Tracking Webhooks","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/direct-carrier-connections/tracking-webhooks.md","pageBaseUrl":"/docs/direct-carrier-connections/tracking-webhooks","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Tracking Webhooks","id":"tracking-webhooks"},{"depth":2,"value":"How it works","id":"how-it-works"},{"depth":2,"value":"Before you start","id":"before-you-start"},{"depth":2,"value":"Two ways to set it up","id":"two-ways-to-set-it-up"},{"depth":2,"value":"Set it up in the Shipwell app","id":"set-it-up-in-the-shipwell-app"},{"depth":2,"value":"Endpoints","id":"endpoints"},{"depth":2,"value":"Step 1: Register your URL","id":"step-1-register-your-url"},{"depth":2,"value":"Step 2: Send a test","id":"step-2-send-a-test"},{"depth":2,"value":"Step 3: Receive tracking.updated","id":"step-3-receive-trackingupdated"},{"depth":3,"value":"Headers","id":"headers"},{"depth":2,"value":"Verify every delivery","id":"verify-every-delivery"},{"depth":2,"value":"Handle each delivery","id":"handle-each-delivery"},{"depth":3,"value":"Mixing pull and push","id":"mixing-pull-and-push"},{"depth":2,"value":"Retries","id":"retries"},{"depth":2,"value":"Pause, change or remove a webhook","id":"pause-change-or-remove-a-webhook"},{"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":"Tracking Webhooks"},"catalogInfo":null,"link":"/docs/direct-carrier-connections/tracking-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"]}