Skip to main content
Yonne sends a signed HTTP POST to your registered webhook URL whenever an order changes state. This page lists every event type and shows the exact payload shape you’ll receive. See Webhook Setup & Security for how to register your endpoint and verify signatures.

​
Supported events

EventWhen it fires
order.driver_assignedA driver accepts and is assigned to the order
order.picked_upThe driver marks the order as picked up from your location
order.deliveredThe driver marks the order as delivered to the customer
order.failedThe order exhausted all driver dispatch attempts with no driver found
order.status_changedAny other status change not covered by the events above (legacy fallback)

​
Event envelope

Every event uses the same outer envelope: 
{
  "event": "order.driver_assigned",
  "created_at": "2026-05-26T14:30:00.000Z",
  "data": {
    "order_id": "ORD123456",
    "tracking_number": "YON-ABC123",
    "tracking_url": "https://yonne.app/track/YON-ABC123",
    "status": "Awaiting Acceptance",
    "environment": "live",
    "delivery_fee": 3500.0,
    "pickup_address": "Area 18, Lilongwe",
    "delivery_address": "Area 3, Lilongwe",
    "receiver_name": "John Doe",
    "merchant_reference_id": "your-internal-order-id",
    "metadata": {},
    "courier": {
      "driver_name": "James Banda",
      "driver_phone": "+265991234567",
      "vehicle_type": "BIKE"
    }
  }
}
FieldTypeDescription
eventstringThe event type (see catalog above)
created_atISO 8601When the event occurred
data.order_idstringYonne’s internal order identifier
data.tracking_numberstringCustomer-facing tracking reference
data.tracking_urlstringPublic tracking link — safe to share directly with your customer
data.merchant_reference_idstringYour own order ID, echoed back from create-order
data.environmentstringlive or test
data.delivery_feenumberDelivery fee in the smallest currency unit (e.g. tambala for MWK)
data.courierobject | nullDriver details — null until a driver is assigned (see below)
data.metadataobjectCustom key/value object you attached at order creation, echoed back

​
Events

​
order.driver_assigned

Fires when a driver accepts and is assigned to the order. This is the first event that includes a populated courier object. 
{
  "event": "order.driver_assigned",
  "created_at": "2026-05-26T14:30:00.000Z",
  "data": {
    "order_id": "ORD123456",
    "tracking_number": "YON-ABC123",
    "tracking_url": "https://yonne.app/track/YON-ABC123",
    "status": "Awaiting Acceptance",
    "environment": "live",
    "delivery_fee": 3500.0,
    "pickup_address": "Area 18, Lilongwe",
    "delivery_address": "Area 3, Lilongwe",
    "receiver_name": "John Doe",
    "merchant_reference_id": "your-internal-order-id",
    "metadata": {},
    "courier": {
      "driver_name": "James Banda",
      "driver_phone": "+265991234567",
      "vehicle_type": "BIKE"
    }
  }
}
Suggested action: Update your order status to show a driver has been found. Use tracking_url to notify your customer so they can follow the rider in real time.

​
order.picked_up

Fires when the driver marks the order as collected from your pickup location. 
{
  "event": "order.picked_up",
  "created_at": "2026-05-26T14:45:00.000Z",
  "data": {
    "order_id": "ORD123456",
    "tracking_number": "YON-ABC123",
    "tracking_url": "https://yonne.app/track/YON-ABC123",
    "status": "In Transit",
    "environment": "live",
    "delivery_fee": 3500.0,
    "pickup_address": "Area 18, Lilongwe",
    "delivery_address": "Area 3, Lilongwe",
    "receiver_name": "John Doe",
    "merchant_reference_id": "your-internal-order-id",
    "metadata": {},
    "courier": {
      "driver_name": "James Banda",
      "driver_phone": "+265991234567",
      "vehicle_type": "BIKE"
    }
  }
}
Suggested action: Mark the order as “In Transit” in your system and send an estimated delivery notification to your customer.

​
order.delivered

Fires when the driver marks the order as successfully delivered to the customer. 
{
  "event": "order.delivered",
  "created_at": "2026-05-26T15:10:00.000Z",
  "data": {
    "order_id": "ORD123456",
    "tracking_number": "YON-ABC123",
    "tracking_url": "https://yonne.app/track/YON-ABC123",
    "status": "Delivered",
    "environment": "live",
    "delivery_fee": 3500.0,
    "pickup_address": "Area 18, Lilongwe",
    "delivery_address": "Area 3, Lilongwe",
    "receiver_name": "John Doe",
    "merchant_reference_id": "your-internal-order-id",
    "metadata": {},
    "courier": {
      "driver_name": "James Banda",
      "driver_phone": "+265991234567",
      "vehicle_type": "BIKE"
    }
  }
}
Suggested action: Mark the order as complete, release any escrow, and trigger a post-delivery review request to your customer.

​
order.failed

Fires when the order exhausted all driver dispatch attempts and no driver was found. The courier field is null for this event. 
{
  "event": "order.failed",
  "created_at": "2026-05-26T14:50:00.000Z",
  "data": {
    "order_id": "ORD123456",
    "tracking_number": "YON-ABC123",
    "tracking_url": "https://yonne.app/track/YON-ABC123",
    "status": "Failed",
    "environment": "live",
    "delivery_fee": 3500.0,
    "pickup_address": "Area 18, Lilongwe",
    "delivery_address": "Area 3, Lilongwe",
    "receiver_name": "John Doe",
    "merchant_reference_id": "your-internal-order-id",
    "metadata": {},
    "courier": null
  }
}
Suggested action: Mark the order as failed in your system, notify the customer, and trigger any retry or refund logic your business requires.

​
order.status_changed

A legacy fallback event that fires on any status transition not covered by the specific events above. Treat it as a general-purpose status update. 
{
  "event": "order.status_changed",
  "created_at": "2026-05-26T14:32:00.000Z",
  "data": {
    "order_id": "ORD123456",
    "tracking_number": "YON-ABC123",
    "tracking_url": "https://yonne.app/track/YON-ABC123",
    "status": "Pending",
    "environment": "live",
    "delivery_fee": 3500.0,
    "pickup_address": "Area 18, Lilongwe",
    "delivery_address": "Area 3, Lilongwe",
    "receiver_name": "John Doe",
    "merchant_reference_id": "your-internal-order-id",
    "metadata": {},
    "courier": null
  }
}

​
Handling unknown event types

New event types may be added to this catalog over time. Your handler should log and ignore events it doesn’t recognise rather than throwing an error — this prevents future additions from breaking your integration. 
function handleWebhookEvent(event) {
  switch (event.event) {
    case 'order.driver_assigned': /* ... */ break;
    case 'order.picked_up':       /* ... */ break;
    case 'order.delivered':       /* ... */ break;
    case 'order.failed':          /* ... */ break;
    case 'order.status_changed':  /* ... */ break;
    default:
      console.log('Unknown event type — ignoring:', event.event);
  }
}

​
Retry behavior

If your endpoint returns a non-2xx status or times out, Yonne retries with exponential backoff (1 min → 15 min → 60 min, up to 3 retries). Design your handler to be idempotent — receiving the same event twice should not cause duplicate side effects. See Webhook Setup & Security for the full retry table and deduplication pattern.