Webhook delivery and retries

If your endpoint starts failing, we stop sending it traffic for a short while and keep testing
it instead. As soon as a probe delivery succeeds, normal delivery resumes automatically. This is the
standard circuit breaker pattern, applied to each of your endpoints independently.

No event is discarded because of this. Held-back deliveries are retried like any other failed
attempt. You do not need to contact us, replay anything, or change your integration.

What counts as a successful delivery

A delivery succeeds when your endpoint answers HTTP 200–299 within 5 seconds.

Everything else is a failed attempt: a 5xx response, a connection that cannot be opened, a TLS or DNS error, or a response that takes longer than 5 seconds.

Client errors (4xx) are also treated as failures for retry purposes, but they do not trigger the pause described below. The pause protects endpoints that are genuinely struggling, not endpoints that are deliberately rejecting a request.

The five-second limit is strict, and it covers the whole exchange including TLS setup. If your
handler does its processing before replying, it will exceed the limit under load and every delivery
will be recorded as failed — even though your service received and processed the event. Return
200 first, process afterwards.

When delivery is paused

Two things have to be true at the same time for one endpoint:

1. At least half of recent delivery attempts to a single web-hook endpoint are failing, and
2. it is receiving sustained, high-volume traffic — a quiet endpoint is never paused.

Only that endpoint is affected. Your other endpoints keep receiving events, and your test-mode (sandbox)
endpoints are tracked completely separately from your live ones.

How the pause clears

While an endpoint is paused, we keep letting a single probe delivery through at widening intervals. The
first one that gets a 2xx clears the pause immediately and full delivery resumes — normally within
minutes of your endpoint recovering. You do not have to tell us that you are back.

What happens to your events meanwhile

They queue up and retry on the standard schedule: the first retries come within seconds, and the
interval grows with each attempt up to a maximum of about six hours. Random jitter is added so a
recovering endpoint is not hit by its whole backlog at once.

An event keeps being retried for up to 72 hours from creation, after which it is given up on.
That limit is unchanged by the pause — a paused delivery does not bring the event closer to being
abandoned, because the cutoff is based on the event's age, not on how many attempts it has had.

Because the intervals grow, an endpoint that was down for a long time does not receive its entire
backlog the moment it recovers — queued events arrive over the following minutes and hours as their
individual retry timers come due.

What you should do

During an outage: nothing. Fix your endpoint; delivery resumes on its own.

To avoid being paused in the first place:

• Answer quickly. Return 2xx as soon as you have safely received the event and do the
  processing asynchronously. You should not be calling GET /events/{event_id} on ProcessOut API or invoking other calls/logic before responding with 2xx on the web-hook. This is the single most common cause of avoidable failures.
• Do not return 5xx for business rejections. An event you do not care about, an unknown event
  type, or a duplicate should get a 2xx. Returning 500 for "I don't handle this" makes a healthy
  endpoint look broken.
• Use 429 if you need us to slow down. It is treated as a normal failed attempt and retried.
• Retire endpoints properly. If you have decommissioned a URL, delete the webhook endpoint in
  your dashboard instead of leaving it answering 404 or 410 — otherwise we keep delivering to it
  for as long as it exists.
• Handle events idempotently. A delivery can be recorded as failed even though your service
  received and processed it — for example when your response is lost, or arrives after the
  five-second limit. Deduplicate on the event id so a repeated delivery is harmless.

Quick reference

Retry schedule

Maximum delay before the next attempt. The actual delay is randomised below the maximum, so retries
usually come sooner than the number shown.

An event whose endpoint never answers gets a few dozen attempts before the 72-hour cut-off.

Probe schedule

While an endpoint is paused we let a single delivery through at these intervals, to see whether it
answers again. The first one that gets a 2xx clears the pause immediately and full delivery resumes.

A probe delivery is one of your real queued events, not a synthetic ping — if it succeeds, that event
is delivered. So an endpoint that stays down is tried about every 7 minutes, and an endpoint that
comes back is picked up at most 7 minutes later.

Frequently asked

Will I lose events while my endpoint is paused?
No. Held-back deliveries are retried like any other failed attempt, within the same 72-hour window.

Do I have to tell you when my endpoint is back?
No. A probe delivery finds out on its own, normally within minutes.

Can I opt out?
It can be turned off for your account — contact support if you have a reason to. Be aware that with
it off, a failing endpoint simply receives a far larger number of doomed requests, and the events
end up equally delayed.

Does this change signatures, headers or payloads?
No. Nothing about the request itself changes.

My test-mode endpoint is failing. Does that affect live?
No. Live and test mode are tracked independently for the same endpoint.