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

AttemptSent after the previous failure
1immediately, once the order settles
21 minute
35 minutes
415 minutes
51 hour
63 hours
76 hours
812 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

  • https or http. Use https.
  • We do not follow redirects. A 301 to 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 localhost and 10.x will not work from our production environment. For local development, use a tunnel.

Answer fast, work later

Acknowledge, then do the work:

The shape that survives loadjs
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.