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:

  1. A URL we can reach. https or http are both accepted, and you should use https.
  2. 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

Headershttp
Content-Type: application/json
User-Agent: GetElectric-Webhooks/1
X-GetElectric-Event: order.settled
X-GetElectric-Signature: t=1763456077,v1=5f0e8b2c91d47a63e8f05c1b7a9d2e4406c3b8f1d95a7e20c48b16d3f9027ace
Bodyjson
{
  "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
}
FieldAlways present
event, mode, reference, state, settled, service, amount, message, settled_atyes
meter_number, disco_code, transaction, token, token_units, refund_amountonly 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