Webhook Events Specification
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.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 | Value | Description |
|---|---|---|
X-Pilot-Delivery | UID | Unique identifier generated for internal tracing |
X-Pilot-Secret | String | Optional; secret value configured at time of subscription |
Custom Headers
You may also configure any number of custom headers that are provided with each payload request. These are sent as-is after a subscription is configured.
Security/Authentication
The payloads sent to the provided URI do not perform any authentication on their own. If you require authentication, you may configure additional headers (see Custom Headers).
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 in the application/json.
Ancillary information specific to the event will differ between different events. (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
Date/time values are expressed in ISO 8601 format, that is, complete date plus hours, minutes, and seconds: YYYY-MM-DDThh:mm:ssTZD (e.g., 2020-07-16T19:20:30+01:00), in the time zone of the event and follow the W3C standards.
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).
eventEnclosure schema:
{
"$schema": "https://json-schema.org/draft/2020-12/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 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": {
"type": "object",
"properties": {
"eventDateTime": {
"format": "date-time",
"type": "string"
},
"event": {
"type": "string"
},
"eventDescription": {
"type": "string"
},
"eventDetail": {
"type": "object",
"properties": {
"housebill": {
"type": "string"
},
"status": {
"type": "string"
},
"statusDescription": {
"type": "string"
},
"location": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
}
}
},
"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": {
"format": "date-time",
"type": "string"
},
"readyDateTime": {
"format": "date-time",
"type": "string"
},
"closeDateTime": {
"format": "date-time",
"type": "string"
},
"scheduledDeliveryDateTime": {
"format": "date-time",
"type": "string"
},
"scheduledDeliveryDateTimeRange": {
"format": "date-time",
"type": "string"
},
"appointmentDateTime": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"appointmentDateTimeRange": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"rescheduledBy": {
"enum": [
"Customer",
"Maersk"
]
},
"totalWeight": {
"type": "number"
},
"totalDimWeight": {
"type": "number"
},
"totalChargeWeight": {
"type": "number"
},
"totalPieces": {
"type": "integer"
},
"podSignature": {
"type": "string"
},
"podDateTime": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"billableCustomerId": {
"type": "string"
},
"shipper": {
"type": "object",
"properties": {
"customerId": {
"type": "string"
},
"name": {
"type": "string"
},
"address1": {
"type": "string"
},
"address2": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
},
"country": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
}
}
},
"consignee": {
"type": "object",
"properties": {
"customerId": {
"type": "string"
},
"name": {
"type": "string"
},
"address1": {
"type": "string"
},
"address2": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
},
"country": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
}
}
},
"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"
}
}
}
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"referenceType": {
"type": "string"
},
"referenceNumber": {
"type": "string"
},
"customerType": {
"type": "string"
}
}
}
},
"statuses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"status": {
"type": "string"
},
"description": {
"type": "string"
},
"statusDateTime": {
"format": "date-time",
"type": "string"
},
"location": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
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.dimensions (schema)
{
"type": "object",
"properties": {
"eventEnclosure": {
"type": "object",
"properties": {
"eventDateTime": {
"format": "date-time",
"type": "string"
},
"event": {
"type": "string"
},
"eventDescription": {
"type": "string"
},
"eventDetail": {
"type": "object",
"properties": {
"housebill": {
"type": "string"
},
"lineItemSequence": {
"type": "integer"
},
"previousDimensions": {
"type": "object",
"properties": {
"pieces": {
"type": "integer"
},
"pieceType": {
"type": "string"
},
"description": {
"type": "string"
},
"length": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"weight": {
"type": "number"
}
}
},
"currentDimensions": {
"type": "object",
"properties": {
"pieces": {
"type": "integer"
},
"pieceType": {
"type": "string"
},
"description": {
"type": "string"
},
"length": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"weight": {
"type": "number"
}
}
}
}
}
}
}
}
}
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
}
}
}
}