Webhook Events Specification
- Getting Started
- Default Headers
- Custom Headers
- Security/Authentication
- Transient Error Handling
- Payload Format
- Event Payload Formats
Overview
Webhooks allow HTTP-based callback functionality for driving event-driven communication between two applications.
Getting Started
The following events can be subscribed to:
| Event | Description |
|---|---|
shipment.status | Triggered when there’s a change in the status of a shipment |
shipment.documents | Triggered when a document is uploaded to a shipment. Refer to Document types for supported types |
shipment.dimensions | Triggered when there’s a modification in the line items of a shipment, such as piece count, description, weight, length, width, or height |
Default Headers
By default, the following headers are included with every payload sent:
| Header | Description |
|---|---|
X-Maersk-Delivery | Unique identifier to your webhook subscription |
X-Maersk-Event | Contains the name of the event |
X-Maersk-Trace-Id | Identifier generated per payload for internal tracing |
X-Maersk-Signature-256 | Optional; Computed signature used for HMAC authentication, see Security/Authentication for more information |
Custom Headers
You may also configure any number of custom headers that are provided with each payload request. These are static and sent as-is after a subscription is configured.
Security/Authentication
When your subscription is created, you have the option to provide a secret token. This token should be a random, high-entropy string stored securely. Maersk will use this secret token to generate a signature for each payload, which is included in the X-Maersk-Signature-256 header. To validate the signature, the payload consumer should generate a hash of the payload using the secret token and compare the results.
Signature Generation Process
- Compute HMAC Signature: The signature is generated using the HMAC (Hash-based Message Authentication Code) algorithm with SHA-256 as the hash function.
- Request Body: The HMAC signature is computed from the payload body and the provided secret token.
- Header Inclusion: The computed signature is then included in the payload headers with the key
X-Maersk-Signature-256.
Transient Error Handling
If a non-successful HTTP status code is received, an event payload will attempt up to five retries. Each retry is delayed (exponentially) by 5 minutes until the maximum retry limit has been reached. If a payload’s maximum retry limit is reached, the subscription is marked as stale to prevent resource usage during extended outages. A stale status prevents any payloads from being sent out until they are manually switched out of this status.
Payload Format
Event payloads are sent as HTTP POST requests to the URI provided at the time of configuration. The requests’ Content-Type is application/json.
Ancillary information specific to the event will differ between event types. (See Event Payload Formats for more information.) However, regardless of event type, each payload will contain an eventEnclosure object with details of the event that was triggered.
Timestamps
All date and time values in the payload follow the ISO 8601 format, adhering to W3C standards.
- Format:
YYYY-MM-DDThh:mm:ssTZD - Example:
2020-07-16T19:20:30+01:00 - Timezone: The time zone reflects the location of the event and is included in the format (TZD).
Unit of measurement
The dimensions specified in the shipment.status and shipment.dimensions payloads are measured in inches, while the weight is expressed in pounds (lbs).
Document types
The following document types can trigger the shipment.documents event:
DeliveryReceiptBillOfLadingShippingLabelPictureProofOfDelivery
eventEnclosure base schema:
{
"type": "object",
"required": [
"eventEnclosure"
],
"properties": {
"eventEnclosure": {
"type": "object",
"required": [
"event",
"eventDateTime",
"eventDescription",
"eventDetail"
],
"properties": {
"eventDateTime": {
"type": "string"
},
"event": {
"type": "string"
},
"eventDescription": {
"type": "string"
},
"eventDetail": {
"type": "object",
"required": [
"housebill",
...
],
"properties": {
"housebill": {
"type": "string"
},
...
}
}
}
}
}
}
eventEnclosure base example:
{
"eventEnclosure": {
"eventDateTime": "2023-11-01T13:39:08",
"event": "shipment.status",
"eventDescription": "Event sent upon a shipment's status changing",
"eventDetail": {
"housebill": "111111111",
...
}
},
...
}
Event Payload Formats
shipment.status (schema)
{
"type": "object",
"properties": {
"eventEnclosure": {
"description": "Enclosure for an event",
"type": "object",
"properties": {
"eventDateTime": {
"description": "Date time (ISO 8601) when the event occurred",
"type": "string",
"format": "date-time"
},
"event": {
"description": "Name of the event",
"type": "string"
},
"eventDescription": {
"description": "Description of the event",
"type": "string"
},
"eventDetail": {
"type": "object",
"properties": {
"housebill": {
"description": "Housebill of the shipment",
"type": "string"
},
"status": {
"description": "Status of the shipment",
"type": "string"
},
"statusDescription": {
"description": "Description of the status",
"type": "string"
},
"location": {
"description": "Location of where the status event took place",
"type": [
"object",
"null"
],
"properties": {
"city": {
"description": "City of the status event location",
"type": "string"
},
"state": {
"description": "State or province (2 letter abbreviation) of the status event location, if applicable",
"type": [
"string",
"null"
]
},
"zip": {
"description": "Zip or postal code of the status event location",
"type": "string"
},
"country": {
"description": "Country (2 letter abbreviation) of the status event location",
"type": "string"
}
},
"required": [
"city",
"zip",
"country"
]
}
},
"required": [
"housebill",
"status",
"statusDescription",
"location"
]
}
},
"required": [
"eventDateTime",
"event",
"eventDescription",
"eventDetail"
]
},
"shipment": {
"type": "object",
"properties": {
"housebill": {
"type": "string"
},
"controlStation": {
"type": "string"
},
"productCode": {
"type": "string"
},
"serviceLevel": {
"type": "string"
},
"originAirport": {
"type": "string"
},
"originArea": {
"type": "string"
},
"originMiles": {
"type": "number"
},
"destinationAirport": {
"type": "string"
},
"destinationArea": {
"type": "string"
},
"destinationMiles": {
"type": "number"
},
"enteredBy": {
"type": "string"
},
"entryDateTime": {
"type": "string",
"format": "date-time"
},
"readyDateTime": {
"type": "string",
"format": "date-time"
},
"closeDateTime": {
"type": "string",
"format": "date-time"
},
"scheduledDeliveryDateTime": {
"type": "string",
"format": "date-time"
},
"scheduledDeliveryDateTimeRange": {
"type": "string",
"format": "date-time"
},
"appointmentDateTime": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"appointmentDateTimeRange": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"rescheduledBy": {
"enum": [
"Customer",
"Maersk",
null
]
},
"totalWeight": {
"type": "number"
},
"totalDimWeight": {
"type": "number"
},
"totalChargeWeight": {
"type": "number"
},
"totalPieces": {
"type": "integer"
},
"podSignature": {
"type": [
"string",
"null"
]
},
"podDateTime": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"billableCustomerId": {
"type": "string"
},
"shipper": {
"type": "object",
"properties": {
"customerId": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"address1": {
"type": "string"
},
"address2": {
"type": [
"string",
"null"
]
},
"city": {
"type": "string"
},
"state": {
"type": [
"string",
"null"
]
},
"zip": {
"type": "string"
},
"country": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"address1",
"city",
"zip",
"country"
]
},
"consignee": {
"type": "object",
"properties": {
"customerId": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"address1": {
"type": "string"
},
"address2": {
"type": [
"string",
"null"
]
},
"city": {
"type": "string"
},
"state": {
"type": [
"string",
"null"
]
},
"zip": {
"type": "string"
},
"country": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"address1",
"city",
"zip",
"country"
]
},
"lineItems": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pieces": {
"type": "integer"
},
"pieceType": {
"type": "string"
},
"description": {
"type": "string"
},
"length": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"weight": {
"type": "number"
}
},
"required": [
"pieceType",
"description"
]
}
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"referenceType": {
"type": "string"
},
"referenceNumber": {
"type": "string"
},
"customerType": {
"type": "string"
}
},
"required": [
"referenceType",
"referenceNumber",
"customerType"
]
}
},
"statuses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"description": {
"type": "string"
},
"statusDateTime": {
"type": "string",
"format": "date-time"
},
"location": {
"type": [
"object",
"null"
],
"properties": {
"city": {
"type": "string"
},
"state": {
"type": [
"string",
"null"
]
},
"zip": {
"type": "string"
},
"country": {
"type": "string"
}
},
"required": [
"city",
"zip",
"country"
]
}
}
}
}
},
"required": [
"housebill",
"controlStation",
"productCode",
"serviceLevel",
"originAirport",
"originArea",
"destinationAirport",
"destinationArea",
"enteredBy",
"billableCustomerId",
"shipper",
"consignee"
]
}
},
"required": [
"eventEnclosure",
"shipment"
]
}
shipment.status (example)
{
"eventEnclosure": {
"eventDateTime": "2024-02-23T13:12:00-07:00",
"event": "shipment.status",
"eventDescription": "Event sent upon a shipment\u0027s status changing",
"eventDetail": {
"housebill": "123456789",
"status": "DEL",
"statusDescription": "DELIVERED",
"location": {
"city": "SALT LAKE CITY",
"state": "UT",
"zip": "84120",
"country": "US"
}
}
},
"shipment": {
"housebill": "123456789",
"controlStation": "SLC",
"productCode": "B",
"serviceLevel": "EC",
"originAirport": "SLC",
"originArea": "A",
"originMiles": 0,
"destinationAirport": "PHL",
"destinationArea": "A",
"destinationMiles": 0,
"entryDateTime": "2024-02-21T09:00:00-08:00",
"readyDateTime": "2024-02-21T09:00:00-08:00",
"closeDateTime": "2024-02-21T17:00:00-08:00",
"scheduledDeliveryDateTime": "2024-02-24T09:00:00-07:00",
"scheduledDeliveryDateTimeRange": "2024-02-24T14:00:00-07:00",
"appointmentDateTime": "2024-02-24T09:00:00-07:00",
"appointmentDateTimeRange": "2024-02-24T14:00:00-07:00",
"rescheduledBy": "Customer",
"totalWeight": 264,
"totalDimWeight": 264,
"totalChargeWeight": 264,
"totalPieces": 1,
"podSignature": "TEST CONSIGNEE",
"podDateTime": "2024-02-24T11:32:14-07:00",
"billableCustomerId": "1234",
"shipper": {
"name": "Test Shipper",
"address1": "404 FIZZ BUZZ AVE",
"city": "SACRAMENTO",
"state": "CA",
"zip": "94203",
"country": "US"
},
"consignee": {
"name": "TEST CONSIGNEE",
"address1": "503 TODO DR",
"city": "SALT LAKE CITY",
"state": "UT",
"zip": "84120",
"country": "US"
},
"lineItems": [
{
"pieces": 1,
"pieceType": "PLT",
"description": "FAK",
"length": 48,
"width": 40,
"height": 28,
"weight": 264
}
],
"references": [
{
"referenceType": "REF",
"referenceNumber": "12345-REF1",
"customerType": "Shipper"
},
{
"referenceType": "REF",
"referenceNumber": "12345-REF2",
"customerType": "Consignee"
}
],
"statuses": [
{
"status": "DEL",
"description": "DELIVERED",
"statusDateTime": "2024-02-24T11:32:14-07:00",
"location": {
"city": "SALT LAKE CITY",
"state": "UT",
"zip": "84120",
"country": "US"
}
},
{
"status": "OFD",
"description": "OUT FOR DELIVERY",
"statusDateTime": "2024-02-24T07:05:00-07:00",
"location": {
"city": "WEST VALLEY CITY",
"state": "UT",
"zip": "84128",
"country": "US"
}
},
{
"status": "APT",
"description": "APPOINTMENT SCHEDULED",
"statusDateTime": "2024-02-22T09:00:00-07:00",
"location": {
"city": "SALT LAKE CITY",
"state": "UT",
"zip": "84120",
"country": "US"
}
},
{
"status": "REV",
"description": "ARRIVED AT PILOT LOCATION",
"statusDateTime": "2024-02-22T06:32:00-07:00",
"location": {
"city": "WEST VALLEY CITY",
"state": "UT",
"zip": "84128",
"country": "US"
}
},
{
"status": "COB",
"description": "IN TRANSIT",
"statusDateTime": "2024-02-21T20:34:00-08:00",
"location": {
"city": "SACRAMENTO",
"state": "CA",
"zip": "95834",
"country": "US"
}
},
{
"status": "PU",
"description": "PICKED UP",
"statusDateTime": "2024-02-21T09:58:00-08:00",
"location": {
"city": "SACRAMENTO",
"state": "CA",
"zip": "94203",
"country": "US"
}
},
{
"status": "DPU",
"description": "DRIVER DISPATCHED FOR PICKUP",
"statusDateTime": "2024-02-21T09:12:00-08:00",
"location": {
"city": "SACRAMENTO",
"state": "CA",
"zip": "95834",
"country": "US"
}
},
{
"status": "NEW",
"description": "SHIPMENT INFORMATION SENT TO PILOT",
"statusDateTime": "2024-02-20T18:34:00-08:00",
"location": {
"city": "SACRAMENTO",
"state": "CA",
"zip": "94203",
"country": "US"
}
}
]
}
}
shipment.documents (schema)
{
"type": "object",
"properties": {
"eventEnclosure": {
"description": "Enclosure for an event",
"type": "object",
"properties": {
"eventDateTime": {
"description": "Date time (ISO 8601) when the event occurred",
"type": "string",
"format": "date-time"
},
"event": {
"description": "Name of the event",
"type": "string"
},
"eventDescription": {
"description": "Description of the event",
"type": "string"
},
"eventDetail": {
"type": "object",
"properties": {
"housebill": {
"description": "Shipment Housebill",
"type": "string"
},
"documentType": {
"description": "Type of document",
"type": "string"
},
"fileName": {
"description": "Name of the document file",
"type": "string"
},
"fileSize": {
"description": "Size of the document file in bytes",
"type": "integer"
},
"mimeType": {
"description": "Mime type of the document",
"type": "string"
},
"retrievalUrl": {
"description": "Uri of where the document file can be accessed",
"type": "string",
"format": "uri"
}
},
"required": [
"housebill",
"documentType",
"fileName",
"mimeType",
"retrievalUrl"
]
}
},
"required": [
"eventDateTime",
"event",
"eventDescription",
"eventDetail"
]
},
"references": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"referenceType": {
"type": "string"
},
"referenceNumber": {
"type": "string"
},
"customerType": {
"type": "string"
}
},
"required": [
"referenceType",
"referenceNumber",
"customerType"
]
}
}
},
"required": [
"eventEnclosure"
]
}
shipment.documents (example)
{
"eventEnclosure": {
"eventDateTime": "2024-04-02T13:00:00-07:00",
"event": "shipment.documents",
"eventDescription": "Event sent upon a new document being uploaded against a shipment",
"eventDetail": {
"housebill": "123456789",
"documentType": "BillOfLading",
"fileName": "123456789_BOL_20240402130000.pdf",
"fileSize": 4300,
"mimeType": "application/pdf",
"retrievalUrl": "https://document-retrieval.pilotdelivers.com/4a3138f5-d9d5-446d-bc11-fe9c816a13a1"
}
},
"references": [
{
"referenceType": "REF",
"referenceNumber": "1232-123432",
"customerType": "Consignee"
}
]
}
shipment.dimensions (schema)
{
"type": "object",
"properties": {
"eventEnclosure": {
"description": "Enclosure for an event",
"type": "object",
"properties": {
"eventDateTime": {
"description": "Date time (ISO 8601) when the event occurred",
"type": "string",
"format": "date-time"
},
"event": {
"description": "Name of the event",
"type": "string"
},
"eventDescription": {
"description": "Description of the event",
"type": "string"
},
"eventDetail": {
"type": "object",
"properties": {
"housebill": {
"description": "Housebill of the shipment",
"type": "string"
},
"lineItemSequence": {
"description": "Sequence (ordering) of the line item",
"type": "integer"
},
"previousDimensions": {
"description": "Previous dimensions of the line item",
"type": "object",
"properties": {
"pieces": {
"description": "Number of pieces in the line item",
"type": "integer"
},
"pieceType": {
"description": "Type of line item piece",
"type": [
"string",
"null"
]
},
"description": {
"description": "Description of the line item",
"type": [
"string",
"null"
]
},
"length": {
"description": "Length of the line item (inches)",
"type": "number"
},
"width": {
"description": "Width of the line item (inches)",
"type": "number"
},
"height": {
"description": "Height of the line item (inches)",
"type": "number"
},
"weight": {
"description": "Weight of the line item (pounds)",
"type": "number"
}
}
},
"currentDimensions": {
"description": "Current dimensions of the line item",
"type": "object",
"properties": {
"pieces": {
"description": "Number of pieces in the line item",
"type": "integer"
},
"pieceType": {
"description": "Type of line item piece",
"type": [
"string",
"null"
]
},
"description": {
"description": "Description of the line item",
"type": [
"string",
"null"
]
},
"length": {
"description": "Length of the line item (inches)",
"type": "number"
},
"width": {
"description": "Width of the line item (inches)",
"type": "number"
},
"height": {
"description": "Height of the line item (inches)",
"type": "number"
},
"weight": {
"description": "Weight of the line item (pounds)",
"type": "number"
}
}
}
},
"required": [
"housebill",
"previousDimensions",
"currentDimensions"
]
}
},
"required": [
"eventDateTime",
"event",
"eventDescription",
"eventDetail"
]
}
},
"required": [
"eventEnclosure"
]
}
shipment.dimensions (example)
{
"eventEnclosure": {
"eventDateTime": "2024-04-02T13:00:00-07:00",
"event": "shipment.dimensions",
"eventDescription": "Event sent upon a shipment\u0027s dimensions changing",
"eventDetail": {
"housebill": "123456789",
"lineItemSequence": 1,
"previousDimensions": {
"pieces": 1,
"pieceType": "BOX",
"description": "FAK",
"length": 1,
"width": 1,
"height": 1,
"weight": 1
},
"currentDimensions": {
"pieces": 1,
"pieceType": "PLT",
"description": "HOME THEATER SET",
"length": 72,
"width": 40,
"height": 36,
"weight": 342
}
}
}
}