Delivery and retries
Eight attempts over about 21 hours, then we stop.
What counts as delivered
Any 2xx. That is the whole test. We do not read your body.
Anything else is a failure and we try again, and that includes 4xx. A 400
because you disliked the payload does not tell us to stop; it buys you eight
deliveries.
A connection we cannot open, a TLS error, or a response that never arrives all count as failures too.
The schedule
| Attempt | Sent after the previous failure |
|---|---|
| 1 | immediately, once the order settles |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 15 minutes |
| 5 | 1 hour |
| 6 | 3 hours |
| 7 | 6 hours |
| 8 | 12 hours |
After the eighth failure we stop and the callback is not sent again. Roughly 21 hours of attempts in total.
Each attempt is signed at the moment it is sent, so a retry carries a fresh t.
A freshness window on your side will not reject our retries.
Warning
Eight attempts is generous, and it is still a limit. An endpoint that was down for a day ends with orders you were never told about. Poll anything still non-terminal, as Order states describes. That reconciliation pass is what makes webhooks safe to rely on.
Seeing what happened
The Webhooks page lists recent deliveries per mode, with the attempt count and when the next one is due. It is the first place to look when an integrator says they never got a callback.
Rules about your URL
httpsorhttp. Usehttps.- We do not follow redirects. A
301to your real endpoint is a failed delivery, so give us the final URL. - It must be reachable from the internet. Private, loopback and link-local
addresses are refused, so
localhostand10.xwill not work from our production environment. For local development, use a tunnel.
Answer fast, work later
Acknowledge, then do the work:
app.post('/webhooks/getelectric', raw, (req, res) => {
if (!signatureIsValid(req)) return res.sendStatus(400)
res.sendStatus(200) // first
enqueue(JSON.parse(req.body)) // then
})A handler that calls three of its own services before answering is a handler that times out under load, which we read as a failure, so you get the event again while the first copy is still being processed. Which is the next point.
Be idempotent
Assume you can see the same event twice: a retry after a response we did not receive, or two callbacks racing. Processing one twice must be harmless.
Key on reference. Before acting, check the state you already recorded. If you
have already marked that order delivered and credited your customer, do
nothing and return 200.