Webhooks

OpenTrack offers the ability for developers to subscribe to a variety of events from our system. When these events occur, we will ping the server defined at the configured webhook URL with the relevant data, allowing you to receive low latency updates for important events generated by the OpenTrack system.

See how to register and consume webhooks

Webhook Delivery Envelope

All webhook events are delivered as an HTTP POST request to your configured URL with the following envelope:

{
  "event": "<event-type>",
  "data": { },
  "changes": { },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

• event — The event type string (e.g. container.status.updated)
• data — The event payload. For most container events this is the full container snapshot (same as GET /v1/container). Some events use a specialized payload — see individual event docs.
• changes — An object showing what changed, with { previous, current } pairs for each modified field. Not present on all events.
• deliveryAttempt — Current delivery attempt number (1-based)
• pendingRetries — Number of remaining retry attempts (up to 5 total)
• sentAt — ISO-8601 timestamp of when the webhook was sent

If a secret is configured on the webhook, the payload is signed and the signature is included in the X-OpenTrack-Signature header.

Default Events

When registering a webhook without specifying events, these are enabled by default:

• container.status.updated
• container.itinerary.updated
• container.location.updated
• container.holds.updated
• container.demurrage.updated

Event Catalog