Delivery Reliability (Retries · Idempotency · Ordering)

Success criterion — 2xx required

A delivery is considered successful only when your webhook returns 2xx. Anything else (4xx, 5xx, timeout, network error) is retried.

warning

4xx responses are retried too. If you received and processed the request normally, always return 2xx — otherwise the same event keeps being re-sent.

Retry policy

The policy below applies to the hosted Gateway (TalkBridge Center).

• Delivery semantics: at-least-once (delivered one or more times — duplicates possible).
• Backoff: 1s → 5s → 30s → 2m → 10m, 5 attempts in total.
• The Gateway persists its delivery ledger, so it resumes incomplete deliveries even after a Gateway restart.
• If all 5 attempts fail, that delivery is marked Failed and the Gateway status is reported as Degraded (overall operation continues).

The CLI relay uses lightweight retries

The CLI Gateway's webhook relay uses lightweight in-memory retries — on transient failure it tries up to 3 times with a 1s → 3s backoff and does not resume from persistence (only while the process is alive). X-Bridge-Delivery-Id is identical across retries, so apply the same idempotency handling on the receiving side. → CLI Gateway

Idempotency

Because you may receive the same event more than once, handle it idempotently.

Deduplication key	Purpose
X-Bridge-Delivery-Id	Removes retry duplicates — retries of the same delivery share the same ID
(brand, seq)	Logical event uniqueness — based on the journal sequence

Recommended: store X-Bridge-Delivery-Id as the primary key and skip deliveries you have already processed.

seq reuse caveat

If the journal is reset, seq may be reused. For long-term idempotency storage, keying on Delivery-Id is safer.

Ordering

• The Gateway tries to preserve send order within a brand, but arrival order can be reversed when retries intervene.
• If order matters, re-sort by the payload's seq (monotonically increasing).

Checklist

• Signature verification failure → 401 (so it keeps failing even when retried)
• Processed normally → 2xx
• Skip duplicates by Delivery-Id
• Filter kind: "agent" echoes
• Even when processing is slow, respond 2xx quickly and post-process asynchronously (avoids the Gateway timeout)