API reference
Download OpenAPIReturns supported carriers, their SCAC codes, and tracking types. Each key in data is a company name, and each value contains scac, cn, bl, and bk. Pass scac as company. Flags set to true indicate support for containers, bills of lading, and bookings respectively.
Authorization
api_key In: query
Response Body
application/json
curl -X GET "https://example.com/v2/companies"{ "success": true, "data": { "Akkon Lines": { "scac": "AKKU", "cn": false, "bl": true, "bk": true }, "Aliança Navegação e Logística Ltda.": { "scac": "ANRM", "cn": true, "bl": true, "bk": true }, "American President Lines": { "scac": "APLU", "cn": true, "bl": true, "bk": true }, "Arkas Container Transport S.A.": { "scac": "ARKU", "cn": true, "bl": true, "bk": true } }}Returns the state of a task created with POST /v2/tracking/batch. In data.status, CREATED means queued, HANDLING means processing, and PROCESSED means complete. Once complete, read data.results and stop requesting the task state. Use tracking requests or webhooks for later shipment updates. Task data is cached for up to 6 hours.
Authorization
api_key In: query
Query Parameters
The unique identifier of the tracking task. It is obtained when creating a request via POST /v2/tracking/batch
uuidResponse Body
application/json
curl -X GET "https://example.com/v2/tracking/batch?task_id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": { "task_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "status": "PROCESSED", "results": [ { "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": 247.34 }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] }, "tracking_metadata": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "end_date": "2025-06-29T14:12:00.000Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2025-06-29T14:12:00.000Z", "updated_at": "2025-06-30T06:00:00.000Z" } }, "status": "OK", "status_description": "Information found", "request": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" } } ] }, "status": "OK"}Creates a task for between 1 and 500 tracking numbers. Processing is asynchronous. The API returns a task_id without waiting for tracking results. Use it with GET /v2/tracking/batch to retrieve the task state and results later. Task data is cached for up to 6 hours.
Authorization
api_key In: query
Query Parameters
Whether to include route information
falseRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/v2/tracking/batch?need_route=false" \ -H "Content-Type: application/json" \ -d '{ "tracked_items": [ { "company": "COSU", "track_number": { "value": "CSNU6184414", "type": "container" } }, { "company": "AKKU", "track_number": { "value": "AKKNEM25072638", "type": "bl" } } ] }'{ "success": true, "data": { "task_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "status": "OK"}Authorization
api_key In: query
Query Parameters
Carrier SCAC code. AUTO is available only for type=container. Use GET /v2/companies to retrieve codes and supported tracking types.
Tracking number type. Container - container, bill of lading - bl, booking - bk.
Value in
- "container"
- "bl"
- "bk"
Tracking number value.
Force refresh tracking data
falseWhether to include route information
falseResponse Body
application/json
curl -X GET "https://example.com/v2/tracking?company=AUTO&type=container&value=CSNU6184414&force_update=false&need_route=false"{ "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": 247.34 }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] }, "tracking_metadata": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "end_date": "2025-06-29T14:12:00.000Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2025-06-29T14:12:00.000Z", "updated_at": "2025-06-30T06:00:00.000Z" } }, "status": "OK", "status_description": "Information found", "request": { "track_number": { "type": "container", "value": "TCKU7858986" }, "company": "MEDU" }}Example request: https://tracking.timetocargo.com/v2/shipments?api_key=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&page=1&limit=50&status=ACTIVE
Authorization
api_key In: query
Query Parameters
Whether to include route information
falsePage number
1 <= value <= 1000000001Number of trackings per page
1 <= value <= 50050Filter shipments by status. Available values: ACTIVE, ARCHIVED
Value in
- "ACTIVE"
- "ARCHIVED"
Response Body
application/json
curl -X GET "https://example.com/v2/shipments?need_route=false&page=1&limit=50&status=ACTIVE"{ "success": true, "data": { "data": [ { "id": "d8976b45-e3e6-4115-b723-57f9b95fc76b", "tracked_item": { "track_number": "MSCU1234567", "track_number_type": "container", "company_id": 60, "data": { "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": 247.34 }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] } }, "status": "OK", "status_description": "Information found" }, "updated_at": "2026-04-08T12:08:55.307Z", "checked_at": "2026-04-08T12:08:55.307Z", "company_name": "Mediterranean Shipping Company" }, "start_date": "2026-04-08T12:26:56.940Z", "end_date": "2026-04-12T09:18:49.395Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2026-04-08T12:08:54.569Z", "track_number": "MSCU1234567" } ], "meta": { "itemsPerPage": 50, "totalItems": 145, "currentPage": 2, "totalPages": 3, "sortBy": [ [ "created_at", "DESC" ], [ "id", "DESC" ] ], "filter": { "status": "$eq:ACTIVE" } }, "links": { "first": "/v2/shipments?page=1&limit=50&status=ACTIVE", "previous": "/v2/shipments?page=1&limit=50&status=ACTIVE", "current": "/v2/shipments?page=2&limit=50&status=ACTIVE", "next": "/v2/shipments?page=3&limit=50&status=ACTIVE", "last": "/v2/shipments?page=3&limit=50&status=ACTIVE" } }, "status": "OK", "status_description": "Information found"}A non-archived tracking record created no more than 72 hours ago is deleted with a refund of one tracking credit if shipment_status is not IN_TRANSIT, including DELIVERED, UNKNOWN, and STUCK. Records with IN_TRANSIT and non-archived records older than 72 hours are archived without a refund. Records that are already archived are deleted without a refund. Deleted IDs are returned in data.deleted, and archived IDs in data.archived.
Authorization
api_key In: query
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X DELETE "https://example.com/v2/shipments" \ -H "Content-Type: application/json" \ -d '{ "shipmentIds": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e", "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ] }'{ "success": true, "data": { "deleted": [ "9ff48bf7-4541-49e2-947c-c269200e030f", "fb8936b9-ff16-4776-8710-d4073ab06d1e" ], "archived": [ "2305a40b-97b2-4c1b-94c4-6d9416b22bde" ] }, "status": "OK", "status_description": "Shipments have been successfully removed"}Updates the shipment note, including for archived shipments. To delete the note, send an empty string { "note": "" } in the request body. Maximum length is 40 characters. Other body fields are rejected.
Authorization
api_key In: query
Path Parameters
Tracked shipment ID
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X PATCH "https://example.com/v2/shipments/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \ -H "Content-Type: application/json" \ -d '{ "note": "Order 123" }'{ "success": true, "data": { "id": "d8976b45-e3e6-4115-b723-57f9b95fc76b", "tracked_item": { "track_number": "MSCU1234567", "track_number_type": "container", "company_id": 60, "data": { "success": true, "data": { "summary": { "origin": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pol": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "pod": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "destination": { "location": 0, "terminal": 0, "date": "2023-03-25T00:00:00" }, "company": { "name": "MSC", "full_name": "Mediterranean Shipping Company", "url": "https://www.msc.com/", "scacs": [ "MEDU", "MSCU" ] } }, "locations": [ { "id": 0, "name": "Gothenburg", "state": "Halland", "terminal": "Port of Gothenburg", "country": "Sweden", "lat": 57.70887, "lng": 11.97456 } ], "terminals": [ { "id": 0, "name": "Port of Gothenburg" } ], "containers": [ { "number": "TCKU7858986", "type": "40' Dry", "events": [ { "location": 0, "terminal": 0, "status": "On Board", "status_code": "CLL", "date": "2023-10-25T11:11:11", "actual": false, "vessel": "Evergreen Teresa", "voyage": "V. 284" } ] } ], "route_info": { "route": [ { "path": [ [ 48.698306, 14.042056 ], [ 45.039944, 12.751222 ], [ 43.463278, 12.6745 ], [ 32.566855, 29.927166 ], [ 32.284501, 31.232806 ] ], "type": "sea" } ], "current_position": [ 32.284501, 31.232806 ], "last_updated": "2023-10-25T11:11:11", "course": 247.34 }, "shipment_status": "IN_TRANSIT", "references": { "booking_numbers": [ "2315887441" ], "bill_of_lading_numbers": [ "MEDUH1234567" ] } }, "status": "OK", "status_description": "Information found" }, "updated_at": "2026-04-08T12:08:55.307Z", "checked_at": "2026-04-08T12:08:55.307Z", "company_name": "Mediterranean Shipping Company" }, "start_date": "2026-04-08T12:26:56.940Z", "end_date": "2026-04-12T09:18:49.395Z", "status": "ACTIVE", "note": "Order 4521", "created_at": "2026-04-08T12:08:54.569Z", "track_number": "MSCU1234567" }, "status": "OK", "status_description": "Information found"}Authorization
api_key In: query
Query Parameters
API key. Provide api_key or its legacy value alias.
uuidDeprecated alias for api_key. Provide api_key or value.
uuidResponse Body
application/json
application/json
curl -X GET "https://example.com/v2/apikey?api_key=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&value=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": { "creation_date": "2023-03-23T21:49:43.000Z", "api_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "requests_remaining_count": 45 }}curl -X GET "https://example.com/v2/webhook-event-types"{ "success": true, "data": [ { "type": "tracking.eta_update", "group": "tracking", "description": "Estimated arrival date changed" }, { "type": "tracking.history_update", "group": "tracking", "description": "An event was added to the tracking history" }, { "type": "tracking.info_found", "group": "tracking", "description": "Tracking data was found" }, { "type": "tracking.info_not_found", "group": "tracking", "description": "Tracking data was not found" }, { "type": "tracking.auto_archiving", "group": "tracking", "description": "Subscriptions were automatically archived" }, { "type": "tracking.delivered", "group": "tracking", "description": "Shipment was delivered" } ], "status": "OK", "status_description": "Request completed successfully"}Returns the webhook delivery history for your callback_url values.
By default, the response includes only failed deliveries. To select another status, pass status=pending or status=delivered. Use webhook_id to limit the results to one webhook.
Results are paginated. The envelope data contains paginated data, meta, and links.
Authorization
api_key In: query
Query Parameters
Delivery status. Defaults to failed.
"failed"Value in
- "pending"
- "delivered"
- "failed"
ID of the webhook whose deliveries should be returned
uuidPage number
1 <= value1Number of deliveries per page
1 <= value <= 10050Response Body
application/json
curl -X GET "https://example.com/v2/webhook-notifications?status=failed&webhook_id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&page=1&limit=50"{ "success": true, "data": { "data": [ { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "webhook_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "event_type": "tracking.delivered", "payload": { "id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "type": "tracking.delivered", "api_version": "2026-07-09", "created_at": "2026-07-08T13:11:22.758Z", "resource": { "tracked_item_id": "eeeeeeee-ffff-aaaa-bbbb-cccccccccccc", "track_number": { "type": "container", "value": "MSBU6501445" }, "company": "Mediterranean Shipping Company", "company_scac": "MSCU" }, "data": { "shipment_status": "DELIVERED", "route": { "origin": "Ho Chi Minh City, VN", "pol": "Wilmington, US", "pod": "Long Beach, US", "destination": "Dallas, US" }, "final_location": "DALLAS, US", "current_position": null, "event": { "location": "DALLAS, US", "status": "Delivered", "status_code": "CDC", "date": "2026-07-07T00:00:00", "actual": true, "vessel": null, "voyage": null } }, "changes": [] }, "status": "delivered", "attempt_count": 1, "next_attempt_at": null, "delivered_at": "2026-07-08T13:16:38.565Z", "created_at": "2026-07-08T13:16:38.371Z", "webhook": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" }, "attempts": [ { "id": "dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb", "notification_id": "cccccccc-dddd-eeee-ffff-aaaaaaaaaaaa", "attempt_number": 1, "http_status": 200, "error_message": null, "attempted_at": "2026-07-08T13:16:38.396Z" } ] } ], "meta": { "itemsPerPage": 50, "totalItems": 1, "currentPage": 1, "totalPages": 1, "sortBy": [ [ "created_at", "DESC" ], [ "id", "DESC" ] ], "searchBy": [], "search": "", "select": [] }, "links": { "first": "/v2/webhook-notifications?page=1&limit=50&status=failed", "previous": null, "current": "/v2/webhook-notifications?page=1&limit=50&status=failed", "next": null, "last": "/v2/webhook-notifications?page=1&limit=50&status=failed" } }, "status": "OK", "status_description": "Request completed successfully"}curl -X GET "https://example.com/v2/webhooks"{ "success": true, "data": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" } ], "status": "OK", "status_description": "Request completed successfully"}Creates a webhook for your account.
The response data includes a signing secret (22 characters from the base64url alphabet: A–Z, a–z, 0–9, -, _). The secret is shown only in this response and is not returned when the webhook is read later, so store it securely immediately.
For each delivery, TimeToCargo sends a POST request to your callback_url. The request contains a WebhookOutgoingPayload JSON object and these headers:
x-timetocargo-signature— HMAC SHA-256 signature oftimestamp + '.' + rawBody, prefixed withsha256=;x-timetocargo-timestamp— Unix timestamp used to generate the signature;x-timetocargo-event-id— unique event ID matchingpayload.id;x-timetocargo-delivery-id— unique delivery attempt ID.
Authorization
api_key In: query
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/v2/webhooks" \ -H "Content-Type: application/json" \ -d '{ "callback_url": "https://example.com/webhooks/timetocargo", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ] }'{ "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z", "secret": "AaBbCcDdEe-_0123456789" }, "status": "OK", "status_description": "Request completed successfully"}Authorization
api_key In: query
Path Parameters
Webhook ID
uuidResponse Body
application/json
curl -X GET "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" }, "status": "OK", "status_description": "Request completed successfully"}Updates the callback_url, activation status, and subscribed event types. With regenerate_secret=true, the response data includes the new secret. It is shown only in that response and is not returned when the webhook is read later.
Authorization
api_key In: query
Path Parameters
Webhook ID
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X PATCH "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" \ -H "Content-Type: application/json" \ -d '{ "is_active": true, "regenerate_secret": false, "event_types": [ "tracking.eta_update", "tracking.history_update" ] }'{ "success": true, "data": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "callback_url": "https://example.com/webhooks/timetocargo", "is_active": true, "event_types": [ "tracking.eta_update", "tracking.history_update", "tracking.info_found", "tracking.info_not_found", "tracking.auto_archiving", "tracking.delivered" ], "created_at": "2026-07-08T09:39:36.311Z", "updated_at": "2026-07-08T13:10:43.554Z" }, "status": "OK", "status_description": "Request completed successfully"}Authorization
api_key In: query
Path Parameters
Webhook ID
uuidResponse Body
application/json
curl -X DELETE "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"{ "success": true, "data": null, "status": "OK", "status_description": "Request completed successfully"}Sends a tracking.test event to your callback_url.
Authorization
api_key In: query
Path Parameters
Webhook ID
uuidResponse Body
application/json
curl -X POST "https://example.com/v2/webhooks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/test"{ "success": true, "data": { "success": true, "http_status": 200 }, "status": "OK", "status_description": "Request completed successfully"}{ "success": true, "data": { "success": false, "http_status": 500, "error_message": "fetch failed" }, "status": "OK", "status_description": "Request completed successfully"}When an event you subscribed to occurs, TimeToCargo sends a POST request to your callback_url.
Return 200 OK as soon as you receive the event. If processing takes time, enqueue the event, send the response, and then process it asynchronously. TimeToCargo waits up to 10 seconds for a response.
Delivery succeeds with any 2xx status. TimeToCargo retries after 408, 409, 425, 429, and 5xx statuses, as well as timeouts and DNS or network errors. It does not retry after 400, 401, 403, 404, or 422. After a 429 response, TimeToCargo honors the Retry-After header when present. Each delivery can have up to five attempts.
To verify the source of the request, use the webhook secret and the x-timetocargo-timestamp and x-timetocargo-signature headers. The signature is an HMAC SHA-256 digest of timestamp + '.' + rawBody, prefixed with sha256=. Use the unchanged request body as rawBody. Signature verification is optional, but recommended.
Node.js / Express
import crypto from 'node:crypto';import express from 'express';const app = express();const secret = process.env.TIMETOCARGO_WEBHOOK_SECRET;if (!secret) { throw new Error('TIMETOCARGO_WEBHOOK_SECRET is not set');}function queueWebhook(payload: unknown): void { // Enqueue the event, save it to your database, // or pass it to another service for processing. console.log('Webhook received from TimeToCargo:', payload);}app.post('/webhooks/timetocargo', express.raw({ type: 'application/json' }), (req, res) => { const timestamp = req.header('x-timetocargo-timestamp'); const signature = req.header('x-timetocargo-signature'); if (!timestamp || !signature) { return res.sendStatus(401); } const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(timestamp).update('.').update(req.body).digest('hex'); const signatureBuffer = Buffer.from(signature); const expectedBuffer = Buffer.from(expected); if (signatureBuffer.length !== expectedBuffer.length || !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) { return res.sendStatus(401); } const payload = JSON.parse(req.body.toString('utf8')); queueWebhook(payload); return res.sendStatus(200);});app.listen(3000, () => { console.log('Webhook server is running on port 3000');});Python / FastAPI
import hmacimport hashlibimport osfrom fastapi import FastAPI, Request, HTTPExceptionapp = FastAPI()secret = os.environ["TIMETOCARGO_WEBHOOK_SECRET"].encode()def enqueue_webhook(payload: dict) -> None: # Enqueue the event, save it to your database, # or pass it to another service for processing. print("Webhook received from TimeToCargo:", payload)@app.post("/webhooks/timetocargo")async def timetocargo_webhook(request: Request): body = await request.body() timestamp = request.headers.get("x-timetocargo-timestamp") signature = request.headers.get("x-timetocargo-signature") if not timestamp or not signature: raise HTTPException(status_code=401) digest = hmac.new( secret, timestamp.encode() + b"." + body, hashlib.sha256, ).hexdigest() expected = f"sha256={digest}" if not hmac.compare_digest(signature, expected): raise HTTPException(status_code=401) payload = await request.json() enqueue_webhook(payload) return {"ok": True}Header Parameters
HMAC SHA-256 signature of timestamp + '.' + rawBody, prefixed with sha256=. Use the unchanged request body as rawBody.
Unix timestamp used to generate the signature
Unique event ID matching payload.id
uuidUnique delivery attempt ID
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
Example Requests
/trackingWebhookDeliveryAPI changelog
Changes in v2 and migration from v1
List supported carriers GET
Returns supported carriers, their SCAC codes, and tracking types. Each key in `data` is a company name, and each value contains `scac`, `cn`, `bl`, and `bk`. Pass `scac` as `company`. Flags set to `true` indicate support for containers, bills of lading, and bookings respectively.