Event: Status Request

event_type: delivery_provider.status_request

Only relevant if you cannot push status updates. Pushing is the default and the better option: it is immediate, cheaper for both sides, and needs no extra endpoint behaviour from you beyond what Pushing Status Updates describes. Implement polling only if your platform genuinely has no outbound webhook capability, and agree it with us during onboarding.

A hybrid is also possible, and is worth raising if it fits your platform: lifecycle statuses arrive by push, while driver position is polled because your pull API returns coordinates only.

🚧
Polling is agreed case by case
No provider integrated so far receives this event at a self-hosted endpoint, so treat it as an arrangement to negotiate rather than a self-service option. If you cannot push, raise it at the start of onboarding: the cadence, the rate limits and the failure handling all need agreeing, and the alternative is that your deliveries have no lifecycle at all.

How polling runs

Once a delivery is dispatched, YUMBI Gateway starts a polling workflow for it and calls this event on an interval until the delivery reaches a terminal status.


Default interval	15 seconds
Maximum duration	3 hours, after which polling stops regardless
Stops early on	Any terminal status — `delivered`, `cancelled`, `failed`, `undeliverable` — from any source, including a pushed update or a cancellation you confirmed

The interval is configurable per environment. Tell us during onboarding if your rate limits need something slower.

Successful polls are not written to the webhook log — at this cadence they would flood it. Failures still are.

Request

{
  "event_id": "5e8a0d42-9f31-4c6b-a7d0-3b1c2e4f5a68",
  "event_type": "delivery_provider.status_request",
  "event_timestamp": 1785063100,
  "user_id": 12,
  "data": {
    "brand_id": null,
    "brand_guid": null,
    "provider_store_id": "STORE-8871",
    "provider_delivery_id": "prv_dl_xyz789",
    "order_guid": "6f1c2b18-3f4d-4f0e-9a6f-2f3b1a9c4d55",
    "order_id": 884213,
    "order_delivery_assignment_id": 5512
  }
}

Field	Type	Notes
`provider_delivery_id`	string	The delivery being polled. Always present.
`order_guid`	UUID \| null	The order it belongs to.
`order_id`	integer \| null	The same order as a number.
`provider_store_id`	string \| null	Your store identifier.
`order_delivery_assignment_id`	integer \| null	YUMBI Gateway's internal id for this delivery attempt.
`brand_id`, `brand_guid`	null	Internal to YUMBI Gateway. Always `null` for you.

Response

Return 200 with the delivery's current state. The field names are the same ones a pushed update uses, so one internal mapping serves both.

{
  "provider_delivery_id": "prv_dl_xyz789",
  "delivery_status": "on_route",
  "driver_full_name": "Sipho Ndlovu",
  "driver_registration": "CA 123-456",
  "vehicle_type": "motorcycle",
  "vehicle_color": "red",
  "driver_latitude": -29.7801,
  "driver_longitude": 30.7842,
  "estimated_time_of_arrival": "2026-08-07T14:41:00+02:00"
}

Field	Type	Notes
`provider_delivery_id`	string	Echo the id you were polled for.
`delivery_status`	string \| null	A canonical status. `null` means "unchanged" — see below.
`driver_full_name`	string \| null
`driver_registration`	string \| null	Vehicle registration or licence plate.
`vehicle_type`	string \| null	Free text, e.g. `motorcycle`, `car`.
`vehicle_color`	string \| null	Free text.
`driver_latitude`	number \| null	Decimal degrees.
`driver_longitude`	number \| null	Decimal degrees.
`estimated_time_of_arrival`	ISO 8601 \| null
`delivery_coords_override`	string \| null	Corrected dropoff coordinates, if you moved the pin.

Return everything you know on every poll. Fields you omit keep their stored value, so nothing is lost by leaving one out, but the poll is your only channel in this mode.

Status changes versus location pings

YUMBI Gateway decides for you. A poll whose delivery_status has not advanced since the last one — or which carries no status at all, as with a coordinates-only API — is treated as a location ping: the driver's position moves on the customer's map without running the status state machine. A poll carrying a new status is a status change.

This means a coordinates-only pull API is a perfectly valid implementation. Return the position and leave delivery_status null; push the lifecycle separately if you can, or map it as best you can from what you have.

Failing a poll

Return a non-2xx. Polling continues on its interval and the next tick tries again. A single failed poll is harmless; sustained failure means the customer's map goes stale, and with polling as your only lifecycle source it means the delivery completes with nothing ever reaching the channel.

If a poll tells you the delivery no longer exists on your side, return the terminal status you do have — cancelled or failed — rather than an error. That ends the polling cleanly instead of letting it run to the three-hour cap.