Delivery guarantees

At-least-once, not exactly-once, and not ordered

Bitelio attempts delivery of every event your endpoint is subscribed to at least once, retrying on failure per the schedule below — but it never guarantees exactly-once delivery, and never guarantees order.

Deduplicate on Bitelio-Idempotency-Id. It's stable across every retry of the same delivery, so the same event can reach your endpoint more than once — a successful attempt whose 200 response was lost in transit, for instance — without you double-processing it.

Order isn't guaranteed. More than one delivery to your endpoint can be in flight at once, and a delivery that fails is retried later with backoff while newer events keep sending — so an event from ten minutes ago can arrive after one from just now. Serialising delivery per endpoint — one at a time, strictly in order — would cap the whole platform's throughput to whatever your slowest receiver can absorb, so Bitelio doesn't do that. If order matters to you, sort by each payload's occurredAt timestamp yourself.

Retries

Any response outside the 2xx range counts as a failure — that includes 3xx/4xx/5xx statuses, a connection error, and a request that doesn't get a response within 10 seconds (treated as a timeout).

A delivery gets up to 9 attempts in total (the first attempt plus 8 retries), spread over roughly 22 hours and front-loaded so a brief outage on your side recovers in seconds:

Each delay has up to ±20% random jitter applied, so a batch of retries doesn't all land on your endpoint at the exact same instant. Once attempt 9 fails, the delivery is marked dead and Bitelio stops retrying it — you'll get an email about it unless an alert for that same endpoint already went out in the last 24 hours (see below), and from that point the only way to receive that event is to replay it manually.

Degradation: when Bitelio stops sending altogether

Failed attempts count against a per-endpoint counter of consecutive failures; any successful delivery resets it to zero. After 10 consecutive failures, Bitelio stops sending your endpoint anything at all — no new deliveries are created for it — so an endpoint that has clearly stopped working doesn't quietly build an ever-growing backlog.

You may receive two different alert emails, and it matters which one you get:

• "Webhook event dropped" — one delivery exhausted its 9 attempts and that event was lost. New events were still being sent when it was dropped. That can change moments later: if your endpoint then crosses the failure threshold you will get a "Webhook delivery stopped" email too, and it is the one that describes the current state.
• "Webhook delivery stopped" — your endpoint just crossed the 10-consecutive-failure threshold and has been marked degraded. Bitelio has stopped sending it anything at all.

So that one incident doesn't fill your inbox, Bitelio sends at most one alert per endpoint per 24 hours — with one deliberate exception: "Webhook delivery stopped" always sends, even if a "Webhook event dropped" email for the same endpoint already went out inside that window. The message that says we've stopped sending is never the one held back. It doesn't work the other way round: once you've been told delivery stopped, dropped-event emails for that endpoint stay quiet for the rest of the window.

Both emails name the last error and the project the endpoint belongs to, and go to every member of that project. Once an endpoint is degraded, Bitelio does not retry on its own or probe the endpoint to see if it recovered — someone has to go to Settings → Webhooks and re-enable it once it's fixed. Re-enabling resets the failure counter to zero and clears the alert, so a second incident later the same day still gets its own email rather than staying silent.

Retention and replay

Delivery history is kept for 30 days, after which the delivery row (and its attempt history) is deleted. The event payload itself is kept for only 7 days — after that the row survives for the rest of the 30-day window, but its payload has already been cleared.

That 7-day window is also the replay window: replaying a delivery re-sends its stored payload, so once the payload is gone there's nothing left to send — attempting to replay it returns an error.

A replay is not a retry: it gets a brand-new Bitelio-Idempotency-Id, different from the original delivery's. That's deliberate. A retry reuses the id specifically so you dedupe it away; a replay is a deliberate re-send that Bitelio expects you to actually process — typically because you fixed a bug in your receiver and are re-asking for events it previously rejected or never received. If replays carried the original id, your dedup logic would silently discard every one of them.

What's next