View as Markdown

Events

Every change you can react to is an event. They're delivered as 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 became an order.

List events

GET /v1/events — newest first, paginated.

Query
type An exact type, or a prefix: order.*
created_gte, created_lt Unix seconds 
curl "$KIBANDA_API/v1/events?type=order.*&created_gte=1792700000" -H "Authorization: Bearer $KIBANDA_KEY"

Retrieve an event

GET /v1/events/{id}