Webhooks
Webhook events
Every event Qoene can send, when it is sent and an example body. Subscribe with these names when you create an endpoint.
Shipment events
shipment.created
A parcel was booked (any channel: API, workspace, ship run).
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.created",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "AWAITING_DROPOFF",
"milestone": "BOOKED",
"view_mode": "IN_TRANSIT"
}
}
}shipment.status_changed
Broad subscription: every shipment transition. Each delivery arrives under its specific name when one exists (for example shipment.delivered).
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.status_changed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.driver_assigned
A rider was assigned to collect or move the parcel.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.driver_assigned",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.driver_arriving
The assigned rider is on the way to collect the parcel.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.driver_arriving",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.dropoff_accepted
The drop-off point accepted and scanned the Relay parcel.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.dropoff_accepted",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "ACCEPTED_AT_DROPOFF",
"milestone": "DROPPED_OFF",
"view_mode": "IN_TRANSIT"
}
}
}shipment.picked_up
A rider collected the parcel.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.picked_up",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.in_transit
The parcel is moving between points or hubs.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.in_transit",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.received_at_hub
The parcel was scanned in at a Qoene hub.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.received_at_hub",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "RECEIVED_AT_HUB",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.arrived_at_pickup
The parcel was received at the buyer's pickup point and is being checked in.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.arrived_at_pickup",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "RECEIVED_AT_PICKUP_POINT",
"milestone": "ARRIVING_AT_POINT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.ready_for_pickup
The buyer can collect the parcel at the point. They have been told.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.ready_for_pickup",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "READY_FOR_PICKUP",
"milestone": "READY_FOR_PICKUP",
"view_mode": "READY_AT_POINT"
}
}
}shipment.ready_in_locker
The parcel was placed in a locker compartment, ready for collection.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.ready_in_locker",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.delivered
An Express (or Relay Home) parcel was delivered to the address.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.delivered",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "DELIVERED",
"milestone": "DELIVERED",
"view_mode": "DELIVERED"
}
}
}shipment.collected
The buyer collected the parcel from the point or locker.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.collected",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "COLLECTED",
"milestone": "COLLECTED",
"view_mode": "DELIVERED"
}
}
}shipment.pickup_failed
The rider could not collect the parcel from the sender.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.pickup_failed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.delivery_attempt_failed
A delivery attempt failed; the tracking exception says what happens next.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.delivery_attempt_failed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.exception
The parcel was put on hold, or reported damaged or lost. See tracking.exception.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.exception",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.return_requested
A return to the sender was requested.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.return_requested",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.return_started
The parcel is on its way back.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.return_started",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.return_at_origin
The returning parcel is back at its origin point.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.return_at_origin",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.returned
The parcel was returned to the sender.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.returned",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.cancelled
The parcel was cancelled.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.cancelled",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "CANCELLED",
"milestone": "CANCELLED",
"view_mode": "EXCEPTION"
}
}
}shipment.out_for_delivery
The parcel left for the delivery address. An endpoint subscribed to this name receives that transition under it; other endpoints keep receiving it as before (for example shipment.driver_arriving).
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.out_for_delivery",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "OUT_FOR_DELIVERY",
"milestone": "OUT_FOR_DELIVERY",
"view_mode": "OUT_FOR_DELIVERY"
}
}
}shipment.pickup_expiring
Less than 24 hours remain to collect from a point (or the final hour for a locker). Adds data.pickup = { expires_at, location_type }. Sent once per hold.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.pickup_expiring",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "READY_FOR_PICKUP",
"milestone": "READY_FOR_PICKUP",
"view_mode": "READY_AT_POINT"
},
"pickup": {
"expires_at": "2026-10-31T18:00:00.000Z",
"location_type": "POINT"
}
}
}shipment.promise_revised
The delivery promise changed (late drop-off, receiver choice, home fallback or operations), with the reason code.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.promise_revised",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.promise_missed
The promised date passed without delivery or collection. Sent once per promise revision.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.promise_missed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.home_attempt_failed
Relay Home: the one home attempt failed. Adds data.home_delivery = { attempt_reason, fallback_point_code, fallback_point_name, route }.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.home_attempt_failed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.redirected_to_point
Relay Home: the parcel is going to the fallback Qoene Point chosen at booking (same data.home_delivery). The buyer collects it there with a pickup code.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.redirected_to_point",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.receiver_changed
The verified receiver changed the destination Qoene Point or locker, the Relay Home fallback point, or extended the hold. Adds data.receiver_change = { id, kind, reason, from_point_code, to_point_code, to_point_name, extension_hours, hold_ends_at, amount_minor }.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.receiver_changed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.overstay_started
The free hold ended and overstay now applies. Adds data.overstay = { hold_ended_at, location_type, rate_per_day_minor, cap_minor, return_after }.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.overstay_started",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}shipment.overstay_paid
All overstay is paid and the parcel can be collected. Adds data.overstay = { amount_minor, paid_by, business_covered_minor, receiver_paid_minor }; paid_by is RECEIVER, BUSINESS (your wallet, under your contract) or SPLIT.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "shipment.overstay_paid",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}Payment events
payment.confirmed
A prepaid parcel's payment is confirmed. Only this means paid.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "payment.confirmed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "AWAITING_DROPOFF",
"milestone": "BOOKED",
"view_mode": "IN_TRANSIT"
}
}
}payment.failed
A payment attempt definitely failed. Pending or uncertain attempts are never reported as failed.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "payment.failed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}refund.processed
A refund was confirmed by the payment provider.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "refund.processed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}locker.overage_due
An overstay fee was assessed (worked out automatically at pickup since NB26). Follow shipment.overstay_paid to know it is settled.
Body: WebhookShipmentEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "locker.overage_due",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"service": "RELAY",
"status": "IN_TRANSIT",
"milestone": "IN_TRANSIT",
"view_mode": "IN_TRANSIT"
}
}
}Order events
order.created
A store order entered the order inbox (any channel except TEST keys).
Body: WebhookOrderEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "order.created",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"order": {
"id": "QD-ORD-9E4B2A7C1F5D38E0A6C4B2F1",
"external_order_id": "1001",
"order_reference": "SHOP-1001",
"store_id": "QD-STR-6A2F9C1E7B3D05A8F4C2E1B9",
"source": "API",
"service_code": "RELAY_POINT",
"status": "AWAITING_SHIPMENT",
"shipment": null,
"failure": null,
"ship_job_id": null
}
}
}order.shipped
A ship run created the order's shipment: data.order.shipment has its ID and tracking number.
Body: WebhookOrderEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "order.shipped",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"order": {
"id": "QD-ORD-9E4B2A7C1F5D38E0A6C4B2F1",
"external_order_id": "1001",
"order_reference": "SHOP-1001",
"store_id": "QD-STR-6A2F9C1E7B3D05A8F4C2E1B9",
"source": "API",
"service_code": "RELAY_POINT",
"status": "SHIPMENT_CREATED",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"failure": null,
"ship_job_id": "QD-SHJ-2B8E4F1A9C7D06E3B5A1F8C2"
}
}
}order.failed
A ship run could not ship the order: data.order.failure has the code and message. Fix the order and ship it again.
Body: WebhookOrderEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "order.failed",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"order": {
"id": "QD-ORD-9E4B2A7C1F5D38E0A6C4B2F1",
"external_order_id": "1001",
"order_reference": "SHOP-1001",
"store_id": "QD-STR-6A2F9C1E7B3D05A8F4C2E1B9",
"source": "API",
"service_code": "RELAY_POINT",
"status": "FAILED",
"shipment": null,
"failure": {
"code": "PARCEL_DETAILS_MISSING",
"message": "Add the parcel weight and size, then ship again."
},
"ship_job_id": "QD-SHJ-2B8E4F1A9C7D06E3B5A1F8C2"
}
}
}Claim events
claim.submitted
A claim was filed on one of your parcels, from the Business workspace or with a LIVE key.
Body: WebhookClaimEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "claim.submitted",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"claim": {
"id": "QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4",
"reason": "DAMAGE",
"status": "SUBMITTED",
"declared_value_minor": 25000,
"approved_minor": null,
"currency": "GHS",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"created_at": "2026-10-27T10:15:00.000Z"
}
}
}claim.under_review
Qoene support started reviewing the claim.
Body: WebhookClaimEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "claim.under_review",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"claim": {
"id": "QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4",
"reason": "DAMAGE",
"status": "UNDER_REVIEW",
"declared_value_minor": 25000,
"approved_minor": null,
"currency": "GHS",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"created_at": "2026-10-27T10:15:00.000Z"
}
}
}claim.approved
The claim was approved in full: data.claim.approved_minor is the compensation in pesewas.
Body: WebhookClaimEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "claim.approved",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"claim": {
"id": "QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4",
"reason": "DAMAGE",
"status": "APPROVED",
"declared_value_minor": 25000,
"approved_minor": 25000,
"currency": "GHS",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"created_at": "2026-10-27T10:15:00.000Z"
}
}
}claim.partly_approved
The claim was approved for part of the amount. Read the reason with GET /claims/{claimId}.
Body: WebhookClaimEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "claim.partly_approved",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"claim": {
"id": "QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4",
"reason": "DAMAGE",
"status": "PARTLY_APPROVED",
"declared_value_minor": 25000,
"approved_minor": 15000,
"currency": "GHS",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"created_at": "2026-10-27T10:15:00.000Z"
}
}
}claim.rejected
The claim was not approved. Read the reason with GET /claims/{claimId}.
Body: WebhookClaimEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "claim.rejected",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"claim": {
"id": "QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4",
"reason": "DAMAGE",
"status": "REJECTED",
"declared_value_minor": 25000,
"approved_minor": null,
"currency": "GHS",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"created_at": "2026-10-27T10:15:00.000Z"
}
}
}claim.paid
The compensation was sent: Business wallet credit, a refund to the original payment, or Mobile Money.
Body: WebhookClaimEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "claim.paid",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"claim": {
"id": "QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4",
"reason": "DAMAGE",
"status": "PAID",
"declared_value_minor": 25000,
"approved_minor": 25000,
"currency": "GHS",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"created_at": "2026-10-27T10:15:00.000Z"
}
}
}claim.withdrawn
The claim was withdrawn before a decision.
Body: WebhookClaimEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "claim.withdrawn",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"claim": {
"id": "QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4",
"reason": "DAMAGE",
"status": "WITHDRAWN",
"declared_value_minor": 25000,
"approved_minor": null,
"currency": "GHS",
"shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB"
},
"created_at": "2026-10-27T10:15:00.000Z"
}
}
}Return events
return.requested
A return was started. A customer-started return in REQUESTED waits for your review.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.requested",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "REQUESTED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": null,
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.approved
The return was approved (by you, your API or your policy) and its return parcel booked.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.approved",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "AWAITING_DROPOFF",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.rejected
You rejected the return; the customer got your reason by SMS.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.rejected",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "REJECTED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": null,
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.cancelled
The return was cancelled before drop-off.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.cancelled",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "CANCELLED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.expired
The drop-off code expired unused; the unused return parcel was cancelled and any charge given back.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.expired",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "EXPIRED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.dropped_off
The customer handed the return to a Qoene Point (or the rider).
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.dropped_off",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "DROPPED_OFF",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.in_transit
The return is moving through the network.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.in_transit",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "IN_TRANSIT",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.arrived
The return is ready for you at your return point.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.arrived",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "ARRIVED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.received
The return was handed to you. Refund the customer from your shop when you are ready.
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.received",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "RECEIVED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": null,
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.inspected
You recorded the condition of the returned goods (data.return.inspection_condition).
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.inspected",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "INSPECTED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": "AS_NEW",
"refund_method": null,
"refund_amount_minor": null,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}return.refund_recorded
You recorded the customer refund (data.return.refund_method, refund_amount_minor).
Body: WebhookReturnEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "return.refund_recorded",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"return": {
"id": "QD-RET-5C2E8A1F9B3D07E4A6C1F8B2",
"status": "INSPECTED",
"reason": "WRONG_SIZE",
"product": "RELAY_POINT",
"payer": "MERCHANT",
"price_minor": 900,
"deduct_from_refund_minor": 0,
"currency": "GHS",
"items": [
{
"name": "Kente scarf",
"sku": "KS-1",
"quantity": 1
}
],
"inspection_condition": "AS_NEW",
"refund_method": "MERCHANT_SYSTEM",
"refund_amount_minor": 4500,
"original_shipment": {
"id": "QD-SHP-8F2A61C04B7D93E5A1C6F0B2",
"tracking_number": "QDE-82AF7CCD60392C9372F5EBDB",
"order_reference": "ACC-1042"
},
"return_shipment": {
"id": "QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4",
"tracking_number": "QDE-4C1A9E7B2D5F08E3A6C1B9D4"
},
"order": {
"id": "QD-ORD-0123456789ABCDEF01234567",
"external_order_id": "1042"
},
"created_at": "2026-11-03T10:15:00.000Z"
}
}
}Test event
webhook.test
A test event you queued with POST /webhook-endpoints/{id}/test or from the workspace.
Body: WebhookTestEvent
{
"id": "4f1c2c0e-1b7a-4bb5-9e44-0b1d5f2f3a10",
"type": "webhook.test",
"created_at": "2026-10-28T14:02:11.000Z",
"data": {
"business_id": "QD-BUS-3E7A1C9F5B2D08E4A6C1F3B7"
}
}