Shipment webhook events

Updated June 11, 20262 min read

Shipment webhooks fire on status transitions, metadata changes, and specific carrier reason codes. The trigger HTTP header on every delivery tells you which event fired.

Status triggers

The trigger header carries the status name.

Trigger value	Fires when
`draft`	Shipment created in draft state
`ready_to_ship`	Shipment is ready for carrier collection
`booked`	Carrier accepts the booking
`shipped`	Handed to carrier
`in_transit`	In the carrier network
`out_for_delivery`	On the delivery vehicle
`awaiting_customer_collection`	At a collection point, waiting for customer
`delivered`	Successfully delivered
`failed_delivery_attempt`	Delivery attempt failed
`failed_collection_attempt`	Collection attempt failed
`cancelled`	Cancelled by the merchant
`cancelled_by_carrier`	Cancelled by the carrier
`delayed`	Carrier reports a delay
`error`	Booking or processing error
`missing`	Lost in transit
`suspended`	On hold
`returned`	Returned to sender
`ready_for_return`	Marked for return
`return_in_transit`	Return leg in transit

Metadata triggers

These fire on non-status changes to the shipment.

Trigger value	Fires when
`default_label_update`	Default (carrier) label is generated
`carriyo_label_update`	Carriyo-generated label is generated
`scheduled_collection_update`	Scheduled collection date changes
`scheduled_delivery_update`	Scheduled delivery date changes
`promised_delivery_update`	Promised delivery date changes

Use default_label_update for label-printing automation — the label is not guaranteed to exist the instant the shipment books.

Reason-code triggers

Specific carrier reason codes that can fire a webhook independently of a status change.

Trigger value	Fires when
`customs_cleared`	Customs clearance completed
`handed_over_to_partner`	Handed over to a delivery partner
`address_corrected_by_carrier`	Carrier corrected the address

Payload

The body is the full Shipment object as JSON. No wrapper, no diff. Whatever is current on the shipment record when the webhook fires is what gets sent.

{
  "shipment_id": "SHP-00012345",
  "entity_type": "SHIPMENT",
  "merchant": "ACME",
  "carrier_account": {
    "carrier_account_id": "ca-dhl-uk-001",
    "carrier": "DHL"
  },
  "post_shipping_info": {
    "status": "in_transit",
    "carrier_status": "Out for delivery",
    "tracking_no": "1234567890",
    "tracking_url": "https://..."
  },
  "pickup": {
    "contact_name": "Warehouse London",
    "country": "GB",
    "city": "London"
  },
  "dropoff": {
    "contact_name": "John Smith",
    "country": "GB",
    "city": "Manchester"
  },
  "parcels": [{ "weight": { "value": 1.2, "unit": "kg" } }],
  "items": [{ "sku": "TSHIRT-BLK-M", "quantity": 2 }]
  // ... full shipment fields
}

Conditions

Shipment webhooks support the most granular filtering. Conditions are AND-combined; for OR-style logic, create separate configurations.

Condition	What it filters
Shipment type	Forward, reverse, or consolidated
Delivery type	Home delivery, click-and-collect, etc.
Dropoff geography	Destination country, state, city, area, or postcode
Pickup location	Specific origin locations
Creation source	How the shipment was created (API, connector, Dashboard)