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

# Delivery and retries

> How Payve delivers events, what counts as success, and the retry schedule.

Payve delivers each event **at least once**. If your server does not confirm receipt, Payve tries again, up to nine times over about three days.

> [!WARNING]
>
> At-least-once means you will sometimes receive the same event more than once. Your handler must be
> safe to run twice. See [Handle events safely](/webhooks/handling-events.md).

## What counts as delivered

| Your server answers | Payve treats it as | Retried automatically? |
| - | - | - |
| `2xx` | Delivered | No. Done. |
| `5xx` | Failed | Yes |
| `408` or `429` | Failed | Yes |
| `3xx` (a redirect) | Failed | Yes. Payve does not follow redirects. |
| Any other `4xx` | Failed | **No** |
| No answer within 30 seconds | Failed | Yes |
| Connection refused, DNS or TLS error | Failed | Yes |
| The URL is not `https` or is a private address | Failed | **No** |

> [!WARNING]
>
> A `4xx` other than `408` or `429` stops retries for that event. Do not answer `400` or `401` for
> an event you want to receive again. If your handler has a temporary problem, answer `500` or
> `503`.

## Retry schedule

Each failed attempt schedules the next one.

| Attempt | Sent |
| - | - |
| 1 | As soon as the transaction finishes |
| 2 | 30 seconds after attempt 1 fails |
| 3 | 2 minutes after attempt 2 fails |
| 4 | 5 minutes after attempt 3 fails |
| 5 | 15 minutes after attempt 4 fails |
| 6 | 1 hour after attempt 5 fails |
| 7 | 6 hours after attempt 6 fails |
| 8 | 24 hours after attempt 7 fails |
| 9 | 48 hours after attempt 8 fails |

After the ninth failure the event is marked `dead` and Payve stops trying.

Retries are sent by a scheduled job, so an attempt goes out at or shortly after its time, not to the second.

## What stays the same across retries

* The event `id`.
* The body.

## What changes on each retry

* `X-Payve-Timestamp` and the `t` in `X-Payve-Signature`. Each attempt is signed afresh, so a retry always passes a five-minute timestamp check.

## Delivery statuses

| Status | Meaning |
| - | - |
| `pending` | Created. The first attempt is in progress. |
| `delivered` | Your server answered `2xx`. |
| `failed` | The last attempt failed. A retry is scheduled, unless the failure was permanent. |
| `dead` | All nine attempts failed. |

## See what happened

List deliveries and inspect one:

```bash
curl "$PAYVE_API_URL/v1/webhooks/events?status=failed&limit=25" \
  -H "x-api-key: $PAYVE_API_KEY"
```

```json
{
  "data": [
    {
      "id": 90211,
      "eventId": "evt_5d0a7c3e9b1f42866e0d1a2b3c4d5e6f",
      "eventType": "payout.successful",
      "status": "failed",
      "attemptCount": 3,
      "lastResponseStatus": 503,
      "lastResponseBody": "Service Unavailable",
      "lastError": null,
      "deliveredAt": null,
      "createdAt": "2026-11-18T10:00:17.000Z",
      "linkedTransactionId": 1842,
      "endpointUrl": "https://example.com/webhooks/payve",
      "endpointId": 12
    }
  ],
  "nextCursor": null
}
```

`GET /v1/webhooks/events/{id}` takes the numeric `id` and returns the exact request Payve sent and the response your server gave.

> [!NOTE]
>
> Payve keeps the first 2,000 characters of your server's response so you can debug a rejected
> delivery. Do not put secrets in webhook responses.

`lastError` values you may see:

| `lastError` | Meaning |
| - | - |
| `Webhook delivery timed out` | No answer within 30 seconds. |
| `Delivery failed: the endpoint could not be reached` | A connection, DNS or TLS problem. |
| `blocked_destination` | The URL is not `https`, or points at a private address. |

## Send an event again

**From the dashboard.** Open **Settings → Webhooks**, find the delivery and select **Retry**. This re-sends the same event with the same `id`.

**From the API.** You can ask Payve to send a fresh event for a finished transaction:

| Request | Scope needed |
| - | - |
| `POST /v1/payouts/{id}/resend-webhook` | `payouts:write` |
| `POST /v1/payins/{id}/resend-webhook` | |
| `POST /v1/conversions/{id}/resend-webhook` | `conversions:write` |

> [!WARNING]
>
> A resend from the API is a **new event**. It has a new `id`, so an event-id check will not
> recognise it as a duplicate. Its `data` is also a shorter summary with camelCase field names. Make
> your handler safe by also checking the transaction's own state before acting. See [Resent
> events](/webhooks/event-samples.md#resent-events).

## If your endpoint was down

1. Fix the endpoint.
2. List deliveries with `status=failed` and `status=dead`.
3. Retry them from the dashboard, or fetch each transaction with a `GET` and reconcile from its status.

> [!TIP]
>
> Do not rely on webhooks alone. Run a periodic job that fetches any transaction still `pending` or
> `processing` after longer than you expect, and reconcile daily against a
> [statement](/guides/statements.md).
