Webhook events

You choose which events each endpoint receives. Every event has the same payload shape (see Webhooks): data.id is the id of what changed and data.status its status after the change.

`order.status_changed`

Shown in the portal as Order status changed. An order was created or its status changed, for example to RESERVED, WEIGHED, SHIPPED or CANCELLED.

Sent when: An order is created (its first status) and every time its status changes afterwards, whether the change came from the API, the portal, a connected store or our team.
data.id: Order id. Fetch it with GET /v1/orders/{id}.
data.status: one of NEEDS_ATTENTION, READY, BACKORDERED, RESERVED, WEIGHED, SHIPPED, CANCELLED.

Shown in the portal as Order needs payment to ship. Your available balance didn't cover the shipping and handling fee when the parcel was weighed. The order waits for a top-up; GET the order for the amount due.

Sent when: Our warehouse weighed the parcel and your available balance didn't cover the shipping and handling fee: sent once per unpaid round, at the same time as the portal notification. A re-weigh in the same round that changes the amount due sends nothing; GET the order for the current amount.
data.id: Order id. GET /v1/orders/{id} shows the amount due.
data.status: Always RESERVED.

`purchase_order.status_changed`

Shown in the portal as Purchase order status changed. A purchase order was created or its status changed.

Sent when: A purchase order is created (status AWAITING_PAYMENT) and every time its status changes afterwards.
data.id: Purchase order id. Fetch it with GET /v1/purchase-orders/{id}.
data.status: one of AWAITING_PAYMENT, DEPOSIT_PAID, PAID, PURCHASING, ORDERED, IN_TRANSIT, PARTIALLY_ARRIVED, ARRIVED, STORED, COMPLETED, CANCELLED.

`shipment.status_changed`

Shown in the portal as Shipment status changed. A shipment was created by you in the portal, sent to you for confirmation, or changed status.

Sent when: A shipment you can see is created or changes status: one you asked for, or one we prepared and sent you (we don't send events for our drafts).
data.id: Shipment id. Fetch it with GET /v1/shipments/{id}.
data.status: one of DRAFT, PENDING_CONFIRMATION, AWAITING_PAYMENT, PAID, SHIPPED, CANCELLED.

`shipment.tracking_updated`

Shown in the portal as Shipment tracking numbers added. Tracking numbers were added to a shipment. GET the shipment to read them.

Sent when: Tracking numbers are added to a shipment (today this happens when it ships).
data.id: Shipment id. GET /v1/shipments/{id} lists the tracking numbers.
data.status: Always SHIPPED.

`quote.created`

Shown in the portal as New quote ready. We sent you a quote. A new version of a quote has a new id.

Sent when: We send you a quote, and again for each new version (a new version has a new id). The status is always AWAITING.
data.id: Quote id. Fetch it with GET /v1/quotes/{id}.
data.status: Always AWAITING.

`wallet.top_up_approved`

Shown in the portal as Top-up approved. A top-up was approved and credited to your wallet.

Sent when: We approve a pending top-up, or record a top-up for you directly. The status is always CONFIRMED.
data.id: Top-up id, as listed by GET /v1/wallet/top-ups.
data.status: Always CONFIRMED.

Test events

webhook.test is sent only when you click Send test event in the portal. Its data.id is the endpoint's id and data.status is TEST. You can't subscribe to it. See Webhook delivery and retries.

Good to know

Events cover changes from every source: the API, the portal, connected stores and our team.
A newly created resource and a status change look the same: the payload doesn't say what the status was before.
If something changes and changes back within one update, no event is sent.
Events are recorded only while API access is on for your account, for endpoints that are on and subscribed to that event.

No event is sent for:

Changing an order's tracking number after it shipped.
Accepting or declining a quote.
Rejecting a top-up.
Voiding an approved top-up.
A quote expiring or becoming UPDATING or SUPERSEDED: these are worked out when you read the quote, not written as changes.