Retry Behavior
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.
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