Skip to Content
WebhooksDelivery & recovery

Delivery, retries and recovery

Delivery is at least once and unordered. The same occurrence can arrive repeatedly, and an older retry can follow a newer update. Store occurrence IDs durably and reconcile current state when needed.

Respond to a delivery

Accept the event durably within 10 seconds. Process slow work through a queue or transactional inbox.

ResponseStello behavior
2xxSuccess. The response body is ignored
4xxTerminal failed delivery. The same request is not automatically retried
5xxRetried with backoff
Network failure or timeoutRetried with backoff
3xxRedirect is refused and handled as a transport failure

The retry policy uses exponential backoff over roughly a day. A receiver needing a temporary retry should return a server error. Authentication or payload errors need a receiver fix and recovery through the dashboard.

Durable receiver outline

app.post('/stello/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify against the RAW bytes. Re-serialising the parsed object changes key
  // order and whitespace, and the signature will not match.
  const raw = req.body.toString('utf8');
  if (!verify(raw, req.header('Stello-Signature') ?? '', process.env.STELLO_SECRET!)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(raw);

  // Answer 200 to types you do not recognise. We add event types over time, and
  // an endpoint subscribed to a family receives new verbs in that family
  // automatically. A 400 here is terminal on our side and counts towards the
  // failure streak that switches your endpoint off.
  switch (event.type) {
    case 'membership.purchased':
      // Idempotent: the same event.id can arrive twice, and order is not
      // guaranteed. Store the id and ignore repeats.
      upsertMember(event.id, event.data.object);
      break;
    default:
      break;
  }

  // Answer fast, work afterwards. We give up on a request after 10 seconds and
  // retry it later, which for a slow database means duplicate work rather than
  // no work.
  res.sendStatus(200);
});

The shared example demonstrates signature verification and dispatch. Replace its illustrative processing with a transactional inbox or durable queue. Commit deduplication and accepted work together so a crash cannot acknowledge work that was never stored. Mark completed work after successful processing and make effects safe to retry.

Endpoint disablement

Stello disables an endpoint after 24 consecutive failed deliveries or 72 hours of uninterrupted failure, whichever threshold applies first, and sends an organization email. Inspect the cause and test the receiver before re-enabling it.

Logs and recovery

Delivery logs and replay data are retained for 30 days. The dashboard can show the first 500 characters of a response body, so keep secrets and personal information out of responses.

Resend an individual delivery or use Send det som mangler to send retained occurrences missing from the endpoint. Manual redelivery creates a new delivery record. Deduplicate by occurrence ID even during recovery.

Recovery covers retained occurrences. Maintain the records and reconciliation your integration needs beyond that window.

Common failures

SymptomCheck
Signature rejectionRaw body bytes, endpoint secret, timestamp and clock accuracy
Repeated timeoutDurable acceptance and the 10-second response budget
No notificationEndpoint enabled state, subscriptions, resource selection and organization feature
Duplicate processingDurable occurrence-ID deduplication and idempotent effects
Older data overwrites newer dataOut-of-order handling and current-state reconciliation

Run the test workflow.