Skip to main content

What counts as success

A delivery succeeds when your endpoint returns any 2xx status within the request timeout (10 seconds). Anything else is a failure and is retried:
  • Non-2xx status codes (4xx, 5xx).
  • Timeouts, DNS failures, and connection errors.
  • Redirects — a 3xx is not followed and is treated as a failure (this prevents a redirect from re-targeting your signed payload).
Riverside reads only a truncated snippet of your response body for the delivery log, so the content of your response doesn’t matter — only the status code.

Retry schedule

Failed deliveries are retried on an exponential backoff. The default schedule is: That’s up to 4 attempts total (the initial attempt plus 3 retries). The delivery_attempt field in the envelope tells you which attempt you’re receiving, and each attempt is recorded in the delivery history.
Because failures are retried, the same event may reach you more than once. Always deduplicate on the envelope id. Delivery order is not guaranteed either — use event_ts if order matters.

Auto-disable

If a delivery exhausts all retries, it is marked FAILED and the subscription is automatically disabled — no further events are delivered until you re-enable it. To recover:
  1. Fix your endpoint.
  2. Re-enable the subscription.
  3. Optionally replay the deliveries that failed or were suspended while it was down.
Auto-disable protects your endpoint and ours from piling up doomed deliveries. Monitor for disabled subscriptions if uptime matters to you — events that occur while a subscription is disabled are not recorded for it and can’t be replayed. Pending or retrying deliveries whose next attempt comes due while it is disabled are marked SUSPENDED (with the error subscription_disabled) and are not sent automatically after re-enabling — replay them to deliver them. Retries that were not yet due when you re-enable are sent on their normal schedule.

Replaying deliveries

Any individual delivery can be re-queued for another attempt — useful after fixing a bug in your handler or re-enabling a subscription. Replaying re-sends the same event envelope (with an incremented delivery_attempt) through the normal delivery path. The subscription must be enabled for the replay to be delivered.

Debugging failed deliveries

Use the delivery history to see, per attempt, the response code, a snippet of your endpoint’s response body, any error message, and the request duration. Filter by status: FAILED or status: SUSPENDED to find deliveries that need attention.