Delivery Guarantees

At-Least-Once Delivery

Event Streaming delivers messages at least once, not exactly once. The same event can arrive at your webhook more than once. This can happen for two reasons:

• Retries: a delivery attempt times out or receives a non-2xx response and is retried, or a target reconnects after a disconnect and receives backlogged messages that overlap with what was already delivered before the disconnect.

❗️

Important Note

Your webhook handler must be idempotent. Deduplicate using the message's uuid field. This is the only field guaranteed to uniquely identify a message.

For unified_confirmed_tx_trace specifically, a transaction's full trace (all internal calls) is delivered as a single message, with every call nested under data.calls. There's no separate message or identifier per call, so deduplicating on the top-level uuid is sufficient.

No Ordering Guarantee

Event Streaming does not guarantee that messages arrive in the order the underlying events occurred on-chain. Don't assume block N arrives before block N+1, or that a transaction's events arrive in execution order. If your application depends on ordering, sort incoming events yourself using block_number (and block_timestamp where available) before processing.

Delivery Failures and Reconnection

A delivery attempt is considered failed on any non-2xx response. Retries use exponential backoff with a maximum period of one minute. After 10 consecutive failed attempts, the target's status changes to failed and delivery stops until the target passes verification again.

While a target is failed or disconnected, messages aren't lost immediately — they're added to the target's topic so they can be delivered on reconnect, up to the retention limits below. See Webhook Handling for the full retry, backoff, and reconnection flow, and Webhook Verification Process for how a target regains "connected" status.

Data Retention

If your target is disconnected longer than the retention windows below, events from that period are permanently lost and won't be backfilled on reconnect.

Security

Every message includes an x-bd-webhooks-signature header — an HMAC-SHA256 signature over the request body using your target's webhook secret. Verify it before trusting the message. See Validate Message Origin for implementation details.