Webhook Payload Structure

JSON envelope and field reference for HellOOpass bill/order webhook events.

Webhook contract

Event names are final (placed, confirmed, rejected, success). The envelope and payload fields below are illustrative until the full webhook specification is published.

Every delivery uses the same envelope: a top-level event wrapper with bill/order data nested under data.

Envelope

{
  "id": "evt_01HZX9K2EXAMPLE",
  "type": "success",
  "api_version": "v1",
  "created_at": "2026-10-20T16:45:00Z",
  "data": {
    "order": {
      "id": "ord_01HZX9K2EXAMPLE",
      "status": "success",
      "amount": 1000,
      "currency": "ETB",
      "reference": "order_1024",
      "metadata": { "order_id": "1024" }
    }
  }
}

Fields

Field	Type	Description
`id`	string	Unique event id — use it as your dedupe key.
`type`	string	Event name: `placed`, `confirmed`, `rejected`, or `success`.
`api_version`	string	Schema version of the event.
`created_at`	string	ISO 8601 timestamp when the event was created.
`data.order.id`	string	HellOOpass bill/order id.
`data.order.status`	string	Bill/order status at emit time.
`data.order.amount`	integer	Amount in the smallest currency unit.
`data.order.reference`	string	Your original order reference, echoed back.

Rules

Dedupe by event id — store id with a unique constraint and ignore repeat deliveries.
Never trust it alone for fulfillment — check amount, currency, and reference against your order first.
Signed means authoritative — verify the signature, process idempotently, and when state conflicts call Verify Payment.