Delivery, retries and endpoint health

This page is what happens on our side: how an endpoint becomes live, what we do when yours is slow or down, when we stop trying, and what we can see when you ask for help.

---

Endpoint lifecycle

A new endpoint starts Pending. Changing its URL returns it to Pending and re-runs verification, so the new URL must be live before you ask for the change. Re-enabling a disabled endpoint does not re-verify it: a URL that was verified resumes as Active, one that was not returns to Pending. Either way it gets a clean five-day window (below).

Verification

Verification sends a real signed delivery of type endpoint.verification.v1 (see Webhook events). Any 2xx within 15 seconds verifies the endpoint and flips it to Active.

Failed pings do not count towards the circuit breaker or auto-disable. An endpoint that has never worked is not a broken endpoint, it is one that is not finished yet.

---

What counts as delivered

That last row is a delivery-time check, not just a registration-time one: we resolve your host, refuse non-public addresses, and connect to the address we vetted, so a DNS record that changes between check and connect cannot redirect a delivery inside a private network.

---

Retries

Failures are retried on a fixed ladder, counted from the failed attempt:

Only age ends an event delivery, not a count of attempts: we keep retrying on that ladder until the delivery is five days old, then mark it Failed and stop. A delivery that is sitting in the ladder still appears in diagnostics, and the event stays readable from GET /v1/events for 90 days either way.

One delivery is in flight per endpoint at a time, oldest first. Two consequences worth designing for:

• Your endpoint never sees a burst of parallel connections from us, however big your backlog is.
• A slow endpoint slows its own queue and nobody else's, and since attempts are serialised per endpoint, a single very slow handler is the most effective way to build a backlog.

There is no ordering guarantee between events. Retries, replays and independent scheduling all reorder. Use occurredAt and a fetch from the API to work out the current state of anything you care about.

---

When an endpoint keeps failing

Degraded (circuit breaker)

After 10 consecutive failed attempts the endpoint's breaker opens and it is marked Degraded. While it is open we stop working through the queue and send one probe every 5 minutes instead. The first probe that succeeds closes the breaker, resets every pending delivery for that endpoint to due-now, and the queue drains in order.

Degraded is a health signal, not a status change: the endpoint is still Active and still subscribed. Verification pings never open the breaker.

Auto-disable

If an endpoint has undelivered events and goes five days without a single successful delivery, we disable it automatically. The disable reason is recorded as AutoDisabledDeliveryFailure and your IFX Payments representative is the one who re-enables it.

The five-day clock is anchored on the later of: the oldest undelivered event, the last time the endpoint went Active, and the last successful delivery. So a re-enabled endpoint gets a fresh window rather than being disabled again immediately by old backlog.

While an endpoint is disabled no delivery records are created at all. Events are still recorded, which is what makes recovery possible:

1. We re-enable the endpoint.
2. We ask for a missed-deliveries replay, which creates deliveries for the events that were never given one (1000 oldest per run).
3. Those deliveries go out through the normal dispatcher, signed, on the normal ladder.

---

Replays

A delivered or failed delivery can be replayed on request. A replay:

• sends the same body, byte for byte, with the same envelope id;
• increments Webhook-Attempt;
• carries a fresh signature with a current created.

So a replay looks exactly like a duplicate to your receiver, which is precisely why de-duplicating on the envelope id matters. Every replay is recorded in an audit log with who asked for it.

---

What we can see when you call support

Quote the Webhook-Delivery-Id. Against it we can see:

Retention is 90 days for deliveries and attempt logs, matching the events window. Ask before that runs out.

---

Limits and numbers in one place