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.
| Response | Stello behavior |
|---|---|
2xx | Success. The response body is ignored |
4xx | Terminal failed delivery. The same request is not automatically retried |
5xx | Retried with backoff |
| Network failure or timeout | Retried with backoff |
3xx | Redirect 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
| Symptom | Check |
|---|---|
| Signature rejection | Raw body bytes, endpoint secret, timestamp and clock accuracy |
| Repeated timeout | Durable acceptance and the 10-second response budget |
| No notification | Endpoint enabled state, subscriptions, resource selection and organization feature |
| Duplicate processing | Durable occurrence-ID deduplication and idempotent effects |
| Older data overwrites newer data | Out-of-order handling and current-state reconciliation |