Webhook Retry Presets

Choose from standard, aggressive, conservative, or no-retry presets to control webhook retry schedules and status-code filters.

8 min read

Use this guide to configure retry behavior for webhook outputs.

Purpose

This guide helps you:

Choose the right retry preset for your webhook reliability needs.
Understand retry schedule differences between presets.
Configure custom status-code filters to retry only specific errors.
Understand tier restrictions on retry presets and status-code overrides.

Retry presets overview

Webhook outputs support four retry presets that control the retry schedule when a delivery fails. The schedules use fixed RabbitMQ delay queues; there is no jitter, custom multiplier, custom delay, or Retry-After header override today.

Preset	Schedule (delays between attempts)	Total attempts	Tier
`STANDARD` (default)	30s → 2m → 10m → 30m → 1h	up to 6 (1 initial + 5 retries)	All tiers
`AGGRESSIVE`	30s → 2m → 10m → 30m → 30m	up to 6 (1 initial + 5 retries)	Pro and higher
`CONSERVATIVE`	5m → 15m → 1h → 6h → 24h	up to 6 (1 initial + 5 retries)	Pro and higher
`NONE`	(no retries)	1	All tiers

All presets retry up to 5 times, but the tier-based retry cap may reduce the effective retry count (see "Tier restrictions" below). Total time budgets for the full schedules are approximately: STANDARD 1h42m30s, AGGRESSIVE 1h12m30s (target schedule rounds up to available queues), CONSERVATIVE 31h20m, and NONE 0ms.

Prerequisites and permissions

Endpoint edit access.
Pro or higher tier to unlock AGGRESSIVE and CONSERVATIVE presets.

Step-by-step workflow

1. Choose a retry preset

Open the endpoint edit page.
Navigate to the Target destinations tab.
Select a webhook output.
In the Retry preset dropdown, choose:
- STANDARD — Balanced retry schedule for most use cases.
- AGGRESSIVE — Faster retries for time-sensitive workflows (Pro+).
- CONSERVATIVE — Slower retries for flaky destinations or rate-limited APIs (Pro+).
- NONE — No retries; fail immediately on first error.
Save.

2. Configure custom status-code filters (Pro+ only)

By default, PayloadRelay retries on:

HTTP 408 (request timeout)
HTTP 429 (rate limit)
HTTP 5xx (server errors)
Transient I/O errors (connection timeout, DNS failure, etc.)

To retry only specific status codes:

Enable Custom retry status codes.
Add retryable status codes as integers (up to 20 values; allowed values are 408, 429, and 5xx, e.g., 502, 503, 504).
Save.

Important: HTTP 429 is always retried, even if not in the custom list. HTTP 2xx/3xx and non-timeout 4xx statuses such as 400, 401, and 404 cannot be configured for retries.

Tier restriction: Custom status-code lists are only available on Pro and higher tiers. Trial/Basic tier is locked to default retry behavior (408 + 429 + 5xx) with 0 retries.

3. Understand tier-based retry caps

The effective number of retries is the lesser of:

The preset's schedule length (5 retries)
The tier's retry limit

Tier	Retry cap	Effective retries (STANDARD/AGGRESSIVE/CONSERVATIVE)
Trial / Basic	0	0
Pro	3	3
Ultimate	5	5
Unlimited	5	5

Example:

Pro tier + STANDARD preset → 3 retries (schedule: 30s → 2m → 10m)
Ultimate tier + CONSERVATIVE preset → 5 retries (full schedule)
Trial / Basic tier + any preset → 0 retries

Preset details

STANDARD (default)

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

Use cases:

General-purpose webhooks with typical downstream availability.
APIs that recover quickly from transient errors.

Behavior:

First retry after 30 seconds allows quick recovery from brief outages.
Later retries give downstream systems time to stabilize.
Total retry window: ~1h 42m.

AGGRESSIVE

Schedule: 30 seconds → 2 minutes → 10 minutes → 30 minutes → 30 minutes

Use cases:

Time-sensitive workflows where delays are costly.
High-availability downstream systems with fast recovery.

Behavior:

Uses a faster retry schedule than the standard preset while still backing off between attempts.
Total retry window: ~72 minutes.

Availability: Pro and higher tiers only.

CONSERVATIVE

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

Use cases:

Flaky or rate-limited downstream APIs.
Destinations with long recovery times (e.g., scheduled maintenance).

Behavior:

First retry after 5 minutes reduces load on struggling systems.
Long delays give downstream systems ample recovery time.
Total retry window: ~31 hours.

Availability: Pro and higher tiers only.

NONE

Schedule: (no retries)

Use cases:

Idempotent workflows with external retry infrastructure.
Testing/debugging where immediate failure is preferred.

Behavior:

Delivery fails immediately after the first attempt.
No retries, no delays.
Failover targets (if configured) are still triggered.

Availability: All tiers.

Default retry behavior (no custom status codes)

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

HTTP 5xx (500, 502, 503, 504, etc.)
HTTP 429 (rate limit)
Transient I/O errors:
- Connection timeout
- Connection refused
- DNS resolution failure
- SSL handshake failure

All other status codes (2xx, 3xx, 4xx except 429) are treated as permanent failures and not retried.

Custom status-code filtering (Pro+ only)

When you configure a custom status-code list:

Only the listed status codes are retried (plus 429, which is always retried).
Transient I/O errors are still retried (connection timeout, DNS failure, etc.).
All other status codes are treated as permanent failures.

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 list)
HTTP 400 → no retry (not in list)
Connection timeout → retry (transient I/O error)

Expected result and verification checks

Webhook deliveries follow the chosen retry schedule.
Failures matching the retry criteria (5xx, 429, or custom list) are retried.
After exhausting retries, the delivery is marked DELIVERY_FAILED in activity logs.
Failover targets (if configured) trigger after retries are exhausted.

Common issues and fixes

Retries not happening: Verify your tier supports the preset. Trial/Basic tier does not include webhook retries (cap is 0).
Custom status codes not working: Ensure you're on Pro or higher tier.
429 not retried: 429 is always retried, regardless of custom list. This is expected behavior.
Too many retries for flaky API: Switch to CONSERVATIVE preset for longer delays.
Retries too slow: Switch to AGGRESSIVE preset for faster retries (Pro+ only).

Interaction with failover

Failover targets trigger after all retries are exhausted. If a webhook output has:

Retry preset: STANDARD (up to 5 retries)
Tier: Ultimate
Failover target: Email

The failover email is sent after the 6th failed attempt (initial + 5 retries).

If the failover target is itself a webhook, it has its own independent retry preset.

Related guides

← Back to documentation