Getting Started

Webhooks

Receive real-time transaction status updates through HTTP webhooks so your application can react when an airtime transaction changes state.

The documentation index identifies Webhooks as a first-class API page. The exact production webhook event schema and signing mechanism will be finalized when we implement the backend.

How webhooks work

Create an airtime transactionYour application sends an authenticated airtime request.
Transaction is processedBuy Airtime communicates with the upstream airtime provider.
Status changesWhen the transaction reaches a new state, the API sends an HTTP POST to your configured webhook URL.
Acknowledge quicklyReturn a successful HTTP response after validating and safely recording the event.

Webhook endpoint

Configure a public HTTPS endpoint in your dashboard. A typical endpoint could be:

Example

POST https://your-app.example.com/webhooks/airtime

Example event

This is a proposed Buy Airtime event shape for the documentation UI; it is not yet the finalized backend contract.

JSON

{{"event":"airtime.transaction.updated","data":{{"reference":"AIR-ORDER-001","status":"completed","phone":"0712345678","amount":100,"network":"safaricom"}}}}

Responding to a webhook

HTTP

HTTP/1.1 200 OK
Content-Type: application/json

{{"received":true}}

Do not trust an event blindly

When webhook signing is implemented, verify the signature before processing the event. Your handler should also be idempotent because webhook delivery may be retried.

Security

Use HTTPS only.
Verify webhook signatures once signing is enabled.
Store the event/reference before triggering downstream work.
Make event processing idempotent.
Return quickly and process expensive work asynchronously where appropriate.