Webhook Retry Presets

Use this guide to set the retry behavior for a webhook destination.

Purpose#

Use this guide to:

• Select a retry preset for the webhook.
• Compare the retry schedules.
• Select the status codes that start another attempt.
• Understand the plan limits for the retry configuration and the status-code overrides.

Retry presets overview#

A webhook destination supports four retry presets. Each preset controls the schedule after a delivery error. The delays are fixed. There is no jitter, custom multiplier, custom delay, or destination Retry-After override.

Preset	Schedule (delays between attempts)	Total attempts	Configuration availability
STANDARD (default)	30s, 2m, 10m, 30m, 1h	up to 6 (1 initial + 5 retries)	All tiers
AGGRESSIVE	30s, 2m, 5m, 15m, 30m	up to 6 (1 initial + 5 retries)	Team trial, Team, Scale, eligible custom plans
CONSERVATIVE	5m, 15m, 1h, 6h, 24h	up to 6 (1 initial + 5 retries)	Team trial, Team, Scale, eligible custom plans
NONE	(no retries)	1	Team trial, Team, Scale, eligible custom plans

A preset with retries has a maximum of 5 delays, but the plan limit can decrease the count. Sandbox and Solo use STANDARD. If no retry is necessary, set the retry count to 0. The full schedule times are approximately STANDARD 1h42m30s, AGGRESSIVE 52m30s, CONSERVATIVE 31h20m, and NONE 0ms.

Before you start#

• Make sure that you can edit the endpoint.
• Use a Team trial, Team, Scale, or eligible custom plan to change the retry policy, select NONE, or configure custom status-code filters.

Procedure#

1. Choose a retry preset#

1. Open the endpoint edit page.
2. Open the Outputs tab.
3. Select a webhook destination.
4. In the Retry preset list, select one:
   • STANDARD: the default schedule for most uses.
   • AGGRESSIVE: faster retries for a time-sensitive workflow on an eligible plan.
   • CONSERVATIVE: slower retries for an unstable destination or a rate-limited API on an eligible plan.
   • NONE: no retries. The delivery fails after the first error, when the plan permits this choice.
5. Save.

2. Configure custom status-code filters (Team trial, Team, Scale, and eligible custom plans)#

By default, PayloadRelay retries after these errors:

• HTTP 408 (request timeout)
• HTTP 429 (rate limit)
• HTTP 5xx (server errors)
• Transient I/O errors (connection timeout, DNS failure, connection refused, or SSL handshake failure)

To retry only selected status codes:

1. Enable Custom retry status codes.
2. Add the retryable status codes as integers. You can add a maximum of 20 values. The permitted values are 408, 429, and 5xx, such as 502, 503, and 504.
3. Save.

PayloadRelay always retries HTTP 429, also when it is not in the custom list. You cannot configure a retry for an HTTP 2xx response, an HTTP 3xx response, or a 4xx response that is not a timeout, such as 400, 401, and 404.

Tier restriction: a custom status-code list is available on Team trial, Team, Scale, and eligible custom plans. Sandbox and Solo use the default retry status policy (408 + 429 + 5xx).

3. Understand tier-based retry caps#

The effective retry count is the lower of these two values:

• The schedule length of the preset (5 retries)
• The retry limit of the tier

Tier	Retry cap	Effective retries (STANDARD/AGGRESSIVE/CONSERVATIVE)	Effective retries (NONE)
Sandbox	1	1	0 (not selectable as an explicit policy)
Solo	3	3	0 (not selectable as an explicit policy)
Team trial / Team	5	5	0
Scale	5	5	0

For a custom plan, the agreement of the organization sets the retry limit.

Example:

• Sandbox with STANDARD: a maximum of 1 retry (30 seconds)
• Solo with STANDARD: a maximum of 3 retries (30s, 2m, 10m)
• Team trial, Team, or Scale with CONSERVATIVE: a maximum of 5 retries (the full schedule)

Preset details#

STANDARD (default)#

Schedule: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour

Use cases:

• A general-purpose webhook with usual availability at the destination.
• An API that recovers quickly from a temporary error.

Behavior:

• The first retry occurs after 30 seconds. This permits a quick recovery from a short outage.
• The later retries give the destination system time to become stable.
• The total retry window is approximately 1h 42m.

AGGRESSIVE#

Schedule: 30 seconds, 2 minutes, 5 minutes, 15 minutes, 30 minutes

Use cases:

• A time-sensitive workflow, where a delay has a high cost.
• A high-availability destination system with a fast recovery.

Behavior:

• The first two retries are the same as STANDARD. The subsequent delays are shorter, and the later attempts occur sooner.
• Each attempt from the third attempt is earlier than STANDARD: 5m against 10m, 15m against 30m, and 30m against 1h.
• The total retry window is approximately 52 minutes. For STANDARD, it is approximately 1h43m.

Availability: Team trial, Team, Scale, and eligible custom plans.

CONSERVATIVE#

Schedule: 5 minutes, 15 minutes, 1 hour, 6 hours, 24 hours

Use cases:

• An unstable destination API, or an API with a rate limit.
• A destination with a long recovery time, for example, during scheduled maintenance.

Behavior:

• The first retry occurs after 5 minutes. This decreases the load on a system that has a problem.
• The long delays give the destination system sufficient time to recover.
• The total retry window is approximately 31 hours.

Availability: Team trial, Team, Scale, and eligible custom plans.

NONE#

Schedule: no retries

Use cases:

• An idempotent workflow (safe to run twice) that has its own retry infrastructure.
• A test, when an immediate failure is necessary.

Behavior:

• The delivery fails immediately after the first attempt.
• There are no retries and no delays.
• PayloadRelay starts a configured failover destination.

Availability: Team trial, Team, Scale, and eligible custom plans for explicit selection. On Sandbox or Solo, set the retry count to 0 and keep STANDARD selected.

Default retry behavior (no custom status codes)#

When Custom retry status codes is not configured, PayloadRelay retries after:

• HTTP 5xx (500, 502, 503, and 504)
• HTTP 408 (request timeout)
• HTTP 429 (rate limit)
• Transient I/O errors:
  • Connection timeout
  • Connection refused
  • DNS resolution failure
  • SSL handshake failure

All the other status codes are permanent errors, and PayloadRelay does not retry them. This includes 2xx, 3xx, and 4xx, but not 408 and 429.

Custom status-code filtering (Team trial, Team, Scale, and eligible custom plans)#

When you configure a custom status-code list:

• PayloadRelay retries only the listed status codes. It also retries 429.
• PayloadRelay still retries a temporary I/O error, such as a connection timeout and a DNS error.
• The other status codes are permanent errors.

Example:

Custom list: [502, 503, 504]

• HTTP 502: retry
• HTTP 503: retry
• HTTP 504: retry
• HTTP 429: retry (always)
• HTTP 500: no retry (not in the list)
• HTTP 400: no retry (not in the list)
• Connection timeout: retry (transient I/O error)

Expected result#

• A webhook delivery follows the selected schedule when the destination has retries.
• PayloadRelay retries an error that agrees with the retry criteria, while retries stay available for the destination.
• After the last retry, Activity marks the delivery as DELIVERY_FAILED.
• A configured failover destination starts after the last retry.

Common issues and fixes#

• Retries do not occur: make sure that the retry count of the destination is more than zero. Make sure that it is not more than the plan limit.
• The custom status codes have no effect: make sure that the plan is Team trial, Team, Scale, or an eligible custom plan.
• 429 is not in the list: PayloadRelay always retries 429.
• Too many retries for an unstable API: select CONSERVATIVE for longer delays.
• The retries are too slow: select AGGRESSIVE on Team trial, Team, Scale, or an eligible custom plan.

Interaction with failover#

A failover destination starts after the last retry. A webhook destination can have this configuration:

• Retry preset: STANDARD (a maximum of 5 retries)
• Plan: Scale
• Failover destination: Email

PayloadRelay sends the failover email after the sixth failed attempt, which is the initial attempt plus 5 retries.

If the failover destination is also a webhook destination, it has its own retry preset.

Related guides#

• Retries and Delivery Behavior
• Relay Targets
• Billing and Usage
• Observability
• Troubleshooting