> ## Documentation Index
> Fetch the complete documentation index at: https://api.vitarelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retries & Delivery

> How VitaRelay retries failed webhook deliveries and when they are dead-lettered.

# Retries & Delivery

## What counts as success

A delivery succeeds when your endpoint returns any `2xx` status (return `200`).
Anything else — `3xx`, `4xx`, `5xx`, a connection failure, or a timeout — is a
failure and will be retried.

<Warning>
  Returning `2xx` only means "received". Do not use the response body to signal
  business outcomes; VitaRelay ignores it.
</Warning>

## Retry behavior

Failed deliveries are retried with **exponential backoff** across a capped number
of attempts. Each retry waits progressively longer than the previous one. After
the final attempt fails, the delivery is **dead-lettered** and no further attempts
are made.

Retries reuse the same `X-VitaRelay-Delivery` id and the same payload, so a
successful retry after a partial failure must not double-apply work on your side.

## Building a reliable endpoint

<Steps>
  <Step title="Verify, then acknowledge">
    Check the signature, persist the raw event, return `200`.
  </Step>

  <Step title="Process asynchronously">
    Push to a queue or background job. Slow inline work causes timeouts, and a
    timeout is a failed attempt.
  </Step>

  <Step title="Be idempotent">
    Store processed `X-VitaRelay-Delivery` ids and short-circuit duplicates.
  </Step>

  <Step title="Monitor">
    Alert on your own 5xx rate for the webhook route, and ask your VitaRelay
    admin to check the last-delivery status shown in the dashboard Webhooks
    panel when you suspect gaps.
  </Step>
</Steps>

## Recovering from a dead-letter

If deliveries were dead-lettered while your endpoint was down, reconcile with the
read API rather than waiting for a replay:

```bash theme={null}
curl https://vitarelay.com/api/public/v1/orders \
  -H "Authorization: Bearer vr_live_xxxx"
```

Then fetch anything that looks stale:

```bash theme={null}
curl https://vitarelay.com/api/public/v1/orders/0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22 \
  -H "Authorization: Bearer vr_live_xxxx"
```

<Note>
  Webhooks are a notification channel, not the system of record. The API is
  always authoritative for current order state.
</Note>