Skip to main content

Webhooks

A webhook has tracking events pushed to a URL you control instead of you polling for them. It's optional: set one up before subscribing if you want event-driven delivery, or skip this page entirely and pull data on demand instead.

1. Configure​

POST /webhook/configure
x-api-key: <your-api-key>
Content-Type: application/json

{
  "targetUrl": "https://domain.com/v1/tracking"
}

A successful call returns {"message": "Successful Configuration"}. See Setup a webhook. Carrier credentials are managed separately; see Carrier Credentials.

You can check the current configuration at any time with GET /webhook/configure.

2. Activate​

Before events will be delivered, confirm your endpoint is reachable and responding:

POST /webhook/activate
x-api-key: <your-api-key>
Content-Type: application/json

{
  "secret": "a1b2c3d4e5"
}

A successful call returns {"message": "Successful Activation"} (or {"message": "Webhook already activated"} if it already was). See Confirm a Webhook is operational.

3. Receive events​

Once active, new tracking events are POSTed to your targetUrl as they're recorded:

{
  "references": {
    "subscriptionReference": "REF12345",
    "equipmentNumber": "ABCU1234567",
    "billNumber": "BL12345",
    "bookingNumber": "BN12345",
    "scacCode": "ABCU"
  },
  "events": [
    {
      "eventType": "EQUIPMENT",
      "equipmentEventTypeCode": "LOAD",
      "eventDateTime": "2023-06-15T10:30:00Z",
      "equipmentReference": "ABCU1234567",
      "eventLocation": { "locationName": "Port of Hamburg", "UNLocationCode": "DEHAM" }
    }
  ]
}

references identifies which subscription the events belong to; events is one or more DCSA events in delivery order. Respond 200 to acknowledge receipt.

Verifying deliveries​

Each delivery includes an X-Hook-Signature header: an HMAC-SHA256 signature of the request body, keyed with your webhook secret. Recompute it on your side and compare before trusting the payload.

If events aren't arriving​

A delivery gap is usually a carrier connectivity problem, not a webhook one; run the carrier health check to find out which.