Skip to content

Shipment delivery status updated
Webhook

Request

Sent when the carrier reports a new delivery status for a shipment. The payload is the shipment as GET /shipments returns it, with the new delivery_status.

Not sent for shipments without a tracking code.

Security
BearerAuth
Headers
x-hive-signaturestringrequired

Hex-encoded HMAC-SHA256 digest of the request body, keyed with your API token (the oldest valid one, if the sales channel has several).

x-hive-event-idstringrequired

Identifies the webhook call. Retries of the same call carry the same value.

Bodyapplication/jsonrequired
created_atstring, (date-time)required

When the shipment was created.

delivered_atstring or null, (date-time)required

When the shipment was delivered.

delivery_statusstring or nullrequired

The latest delivery status reported by the carrier, null until there is one:

  • Information transmitted to the carrier: marked as shipped, no status from the carrier yet.
  • In transit: on the way to the carrier's hub.
  • Out for delivery: left the carrier's hub and is being delivered.
  • Delivered: delivered.
  • Awaiting customer pickup: waiting for the customer at a pickup point.
  • Returned to sender: the carrier is returning it to the sender.
  • Return initiated: a return was initiated.
  • Action required: something unusual happened, such as a failed delivery attempt, a lost parcel or an address problem.
idinteger, (int64)required

Hive's unique identifier for the shipment.

itemsArray of objects(ShipmentItem)required

The items in the shipment.

merchant_order_idstringrequired

The merchant's identifier for the shipment's order.

order_idinteger, (int64)required

Hive's ID of the shipment's order. GET /orders/{id} finds it unless the order was created manually.

shipment_providerstring or nullrequired

The carrier's name.

shipped_atstring or null, (date-time)required

When the shipment was shipped.

statusstringrequired

The fulfillment status of the shipment. GET /shipments only returns shipped shipments; the shipment_status_updated webhook sends every status.

  • created, waiting_for_picking: waiting to be picked.
  • on_hold: on hold, for example because fulfillment starts later, or because of an address problem or missing stock.
  • picking_assigned: a warehouse employee took on picking it.
  • in_picking: being picked.
  • picked: picked, ready for packing.
  • in_packing: being packed.
  • packed: packed, ready for shipping.
  • in_shipping: being shipped.
  • shipped: labelled and left the packing station, waiting for or already picked up by the carrier.
  • cancelled: cancelled, it will not be fulfilled.
  • ignored: will not be fulfilled by Hive.
Enum:"created""waiting_for_picking""on_hold""picking_assigned""in_picking""picked""in_packing""packed""in_shipping""shipped"
tracking_numberstring or nullrequired

The tracking number the carrier assigned.

tracking_urlstring or nullrequired

The carrier's tracking page for the shipment.

updated_atstring, (date-time)required

When the shipment was last updated.

warehouse_idinteger or null, (int64)required

Hive's ID of the warehouse that fulfills the shipment.

Payload
{
  "id": 170,
  "tracking_url": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=CR123456789DE",
  "status": "shipped",
  "delivery_status": "Delivered",
  "created_at": "2022-06-04T03:17:25.533+02:00",
  "updated_at": "2022-07-22T16:53:31.388+02:00",
  "shipped_at": "2022-06-04T07:53:20.511+02:00",
  "delivered_at": "2022-06-06T22:17:46.000+02:00",
  "warehouse_id": 22,
  "order_id": 575,
  "merchant_order_id": "20220604-383",
  "shipment_provider": "DHL",
  "tracking_number": "CR123456789DE",
  "items": [
    { … }
  ]
}

Responses

Any 2xx status acknowledges the webhook.