Webhooks
One event:
order.settled.
When an order reaches a terminal state we POST to your URL once, with the
order's outcome. It is how you stop polling.
Setting it up
On the Webhooks page, per mode:
- A URL we can reach.
httpsorhttpare both accepted, and you should usehttps. - A signing secret. Technically optional. Treat it as required: without it, anyone who learns your URL can post whatever they like to it and you have no way to tell.
webhook_configured on Get account is true
only once both are set for that mode. Test and live have separate URLs and
separate secrets, so a test callback is signed with your test secret.
You can fire a real signed callback at your endpoint from your dashboard before writing any order code, which is the quickest way to get your signature check right.
What we send
Content-Type: application/json
User-Agent: GetElectric-Webhooks/1
X-GetElectric-Event: order.settled
X-GetElectric-Signature: t=1763456077,v1=5f0e8b2c91d47a63e8f05c1b7a9d2e4406c3b8f1d95a7e20c48b16d3f9027ace{
"event": "order.settled",
"mode": "test",
"reference": "alpha-000147",
"state": "delivered",
"settled": true,
"service": "electricity",
"amount": 5000,
"message": "Delivered.",
"settled_at": "2026-11-18T09:14:37+01:00",
"meter_number": "11111111111",
"disco_code": "IKEDC",
"transaction": "TESTSW-9A3F5C1E7B2D4068",
"token": "TEST-4821 9033 7715 2064",
"token_units": 71.4
}| Field | Always present |
|---|---|
event, mode, reference, state, settled, service, amount, message, settled_at | yes |
meter_number, disco_code, transaction, token, token_units, refund_amount | only when they apply |
state here is one of delivered, failed or refunded. A non-terminal order
is never the subject of a callback. refund_amount appears on a refund and is
what went back to your balance.
Warning
The body names no target, provider_id or plan_id. For airtime, data and
cable TV, service and your own reference are the only clues to what was
sold, so you must keep your own mapping from reference to product. If you were
planning to read the phone number off the callback, you cannot.
settled_at is RFC 3339 with an offset, unlike the order endpoints, which
write a bare Z. Parse both with a real RFC 3339 parser.
What we expect back
Any 2xx, and we stop. Nothing in your response body is read.
Anything else is a failure, 4xx included, and we try again. Returning
400 because you did not like the payload does not make us go away; it buys
you eight deliveries over the next day.
Answer quickly. Acknowledge the callback, then do your work: queue it, write a
row, return 200. A handler that calls three of its own services before
answering is a handler that times out under load and gets the same event again.
Order of arrival
There is no ordering guarantee between callbacks for different orders, and a
retried callback can arrive after a later order's first one. Key everything on
reference.
A callback can also arrive before your POST /reseller/orders call has
returned, if the order settles that fast. If your handler looks up a local row
that the ordering code has not written yet, it will not find it. Write your row
before you send the order, not after.
Make it idempotent
We aim to deliver each event once, and you should not depend on that. A
callback you have already processed must be a no-op the second time. Key on
reference, and check the state you already recorded before acting again.
Next
- Verifying a signature, with working code
- Delivery and retries