# Events

Every change you can react to is an event. They're delivered as [webhooks](https://kibanda.africa/docs/webhooks) and kept in a log you can read back — handy for catching up after downtime or backfilling a new system.

## The event object

| Field | |
|---|---|
| `id` | `evt_…` — unique; the same id is sent on every webhook retry. |
| `object` | `"event"` |
| `type` | See below. |
| `created` | Unix seconds when it happened. |
| `data.object` | The object it's about, as it was when the event was first sent. |

## Types

| Type | When |
|---|---|
| `order.created` | A customer placed an order (sent once the short undo window has passed). |
| `order.paid` | The order is fully paid (M-Pesa, card, or cash collected at the door or counter). |
| `order.deposit_paid` | A deposit the shop's terms asked for was paid; the order goes ahead with the rest due on delivery. |
| `order.payment_required` | The shop asked for payment before delivery on this order. |
| `order.payment_failed` | A payment attempt failed or expired. The order stays open; the customer can retry. |
| `order.dispatched` | A rider was assigned (or reassigned). |
| `order.picked_up` | The rider has the order. |
| `order.arrived` | The rider is at the customer. |
| `order.delivered` | Handed over (with the delivery code if the shop uses one). |
| `order.delivery_failed` | Couldn't be delivered (no answer, wrong location, refused). Stock is returned. |
| `order.ready_for_pickup` | A pickup order is ready at the counter. |
| `order.cancelled` | Cancelled by the customer, the shop, or because it went unpaid. Stock is returned. |
| `order.refund_needed` | Money arrived that must be returned (paid twice, or paid after cancelling). |
| `order.rated` | The customer rated the order. |
| `customer.created` | A new customer (first message, or created through the API). |
| `cart.abandoned` | A customer left items in their cart without ordering. Good for a follow-up. |
| `checkout_session.completed` | A [checkout session](https://kibanda.africa/docs/checkout-sessions) became an order. |

## List events

`GET /v1/events` — newest first, [paginated](https://kibanda.africa/docs/pagination).

| Query | |
|---|---|
| `type` | An exact type, or a prefix: `order.*` |
| `created_gte`, `created_lt` | Unix seconds |

```bash
curl "$KIBANDA_API/v1/events?type=order.*&created_gte=1792700000" -H "Authorization: Bearer $KIBANDA_KEY"
```

## Retrieve an event

`GET /v1/events/{id}`