---
title: Retry Behavior
slug: retry-behavior
icon: {"lucideIcon":"RefreshCw"}
createdAt: 2026-11-16T18:09:51.105Z
---

# &#x20;Webhook Retries

When an event happens on an offering, EquiDeFi sends it to every active webhook subscribed to that event. If your endpoint doesn't accept a delivery, we try again. This page covers what counts as a success, when we retry, and what you'll see in the delivery log.

## What counts as a successful delivery

A delivery succeeds when your endpoint answers with any **2xx** status before the request times out. Everything else is a failed attempt:

| Failure            | Details                                                                            |
| ------------------ | ---------------------------------------------------------------------------------- |
| Non-2xx response   | Any 3xx, 4xx or 5xx. Redirects are not followed, so a `301` or `302` is a failure. |
| Timeout            | 5 seconds to connect, 15 seconds to respond, 25 seconds for the whole request.     |
| Connection error   | Connection refused, reset or unreachable.                                          |
| TLS error          | Expired, self-signed or otherwise invalid certificate.                             |
| Response too large | A response body over 64 KB is a failure, even with a 2xx status.                   |

## Retry schedule

Each delivery gets **3 attempts in total**: the first send and up to 2 retries.

| Attempt | When it's sent                         |
| ------- | -------------------------------------- |
| 1       | Right after the event happens          |
| 2       | About 5 seconds after attempt 1 fails  |
| 3       | About 10 seconds after attempt 2 fails |

If all 3 attempts fail, the delivery is marked **Failed** and we stop. We don't retry it later, and there's no resend button.

All attempts are spread over about 15 seconds. If every attempt times out, it takes up to about 90 seconds. If your endpoint is down longer than that (during a deploy, for example), the events sent in that window are not delivered.

:::BlockQuote
**Tip:** Use **Send Test** on the webhook page to confirm your endpoint is reachable after a deploy or URL change.
:::

### Deliveries that are never retried

Some failures can't be fixed by trying again, so the delivery fails on the first attempt:

- **The URL is refused at send time.** Webhook URLs must use `https` and resolve to a public address. If the hostname doesn't resolve, or resolves to a private, loopback or reserved address, nothing is sent and the delivery is marked **Failed** with a `BLOCKED_URL` error.
- **The webhook is disabled.** A delivery waiting on a retry is dropped when its webhook is disabled or deleted. It stays **Pending** and isn't sent when you turn the webhook back on. Events that happen while a webhook is disabled aren't queued for it at all.

## Every attempt sends the same event

Each attempt carries the same payload and the same `X-Webhook-Id` header. The payload is built once, when the event happens, so a retry shows the investment as it was at the event, not at the moment of the retry.

Each attempt is signed again with a new timestamp. `X-Webhook-Timestamp` and the `t=` value in `X-Webhook-Signature` change on every attempt, so a retry passes the 5-minute signature window just like the first send.

## Building a receiver that handles retries

- **Respond fast.** Return a 2xx as soon as you've stored the event, then do the work afterwards. A response that takes longer than 15 seconds counts as a failure, and we send the event again.
- **Deduplicate on `X-Webhook-Id`.** You can receive the same event more than once. For example, you processed it but answered too slowly or with an error. Store the IDs you've handled and skip repeats.
- **Point the webhook at the final URL.** Redirects count as failures.
- **Keep the response body small.** An empty body or a short JSON acknowledgement is enough.
- **Don't rely on order.** Deliveries are sent in parallel and retries are delayed, so a later event can arrive before an earlier one.

## Delivery log

Every delivery shows up in the webhook's delivery log in the issuer portal for 30 days. A retry updates the same row, so one event shows up once per webhook no matter how many attempts it took.

| Field      | Meaning                                                                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Status     | **Pending**: sending, or a retry is still coming. **Delivered**: an attempt got a 2xx. **Failed**: all attempts failed, or the URL was refused. |
| Attempts   | How many attempts were made for this delivery.                                                                                                  |
| Response   | The HTTP status from the most recent attempt. It's blank when there was no response, such as a timeout.                                         |
| Last Error | Why the most recent attempt failed, including the start of your endpoint's response body. It's cleared once an attempt succeeds.                |
| Delivered  | When the successful attempt landed.                                                                                                             |

The error starts with one of these types: `HTTP`, `TIMEOUT`, `CONNECTION`, `TLS` or `BLOCKED_URL`.

Open a delivery to see its full payload. Use **Copy JSON** to replay a failed event into your system by hand.

## Webhook health

The webhook list has a **Last Delivery** column. It shows whichever happened more recently:

- **Succeeded** with the time of the last successful delivery.
- **Failed** with the time of the last failed attempt, plus how many deliveries **in a row** have failed. Only deliveries that used up all of their attempts count toward this number.

A successful delivery resets the count to zero, and so does turning the webhook back on. **We never disable a webhook automatically**, no matter how many deliveries fail. If you want deliveries to stop, disable the webhook yourself.

## Send Test

**Send Test** posts one signed `TEST.SENT` event to the URL in the form, including a URL you haven't saved yet. A test:

- is sent once and never retried
- doesn't appear in the delivery log
- doesn't change the Last Delivery column or the failure count
