← Back to documentation

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 plan limits on retry policy settings 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.

PresetSchedule (delays between attempts)Total attemptsConfiguration availability
STANDARD (default)30s → 2m → 10m → 30m → 1hup to 6 (1 initial + 5 retries)All tiers
AGGRESSIVE30s → 2m → 10m → 30m → 30mup to 6 (1 initial + 5 retries)Team trial, Team, Scale, Unlimited
CONSERVATIVE5m → 15m → 1h → 6h → 24hup to 6 (1 initial + 5 retries)Team trial, Team, Scale, Unlimited
NONE(no retries)1Team trial, Team, Scale, Unlimited

Retrying presets have up to 5 retry delays, but the plan-based retry cap reduces the effective count. Sandbox and Solo stay on STANDARD; set their retry count to 0 when no retries are desired. Total time budgets for the full schedules are approximately: STANDARD 1h42m30s, AGGRESSIVE 1h12m30s, CONSERVATIVE 31h20m, and NONE 0ms.

Prerequisites and permissions

  • Endpoint edit access.
  • Team trial, Team, Scale, or Unlimited to change retry policy away from STANDARD, select NONE explicitly, or configure custom status-code filters.

Step-by-step workflow

1. Choose a retry preset

  1. Open the endpoint edit page.
  2. Navigate to the Target destinations tab.
  3. Select a webhook output.
  4. In the Retry preset dropdown, choose:
    • STANDARD — Balanced retry schedule for most use cases.
    • AGGRESSIVE — Faster retries for time-sensitive workflows (Team trial/Team/Scale).
    • CONSERVATIVE — Slower retries for flaky destinations or rate-limited APIs (Team trial/Team/Scale).
    • NONE — No retries; fail immediately on first error (available when retry configuration is enabled for your plan).
  5. Save.

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

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:

  1. Enable Custom retry status codes.
  2. Add retryable status codes as integers (up to 20 values; allowed values are 408, 429, and 5xx, e.g., 502, 503, 504).
  3. 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 available on Team trial, Team, Scale, and Unlimited. Sandbox and Solo use the default retry status policy (408 + 429 + 5xx).

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
TierRetry capEffective retries (STANDARD/AGGRESSIVE/CONSERVATIVE)Effective retries (NONE)
Sandbox110 (not selectable as an explicit policy)
Solo330 (not selectable as an explicit policy)
Team trial / Team550
Scale / Unlimited550

Example:

  • Sandbox + STANDARD → up to 1 retry (30 seconds)
  • Solo + STANDARD → up to 3 retries (30s → 2m → 10m)
  • Team trial/Team/Scale + CONSERVATIVE → up to 5 retries (full schedule)

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: Team trial, Team, Scale, and Unlimited.

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: Team trial, Team, Scale, and Unlimited.

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 destinations (if configured) are still triggered.

Availability: Team trial, Team, Scale, and Unlimited for explicit selection. On Sandbox or Solo, set the retry count to 0 while keeping STANDARD selected.

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 (Team trial, Team, and Scale)

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 when retries are configured.
  • Failures matching the retry criteria (5xx, 429, or custom list) are retried when the output has retries available.
  • After exhausting retries, the delivery is marked DELIVERY_FAILED in activity logs.
  • Failover destinations (if configured) trigger after retries are exhausted.

Common issues and fixes

  • Retries not happening: Verify the output retry count is above zero and does not exceed the plan cap.
  • Custom status codes not working: Ensure you're on Team trial, Team, Scale, or Unlimited.
  • 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 on Team trial, Team, Scale, or Unlimited.

Interaction with failover

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

  • Retry preset: STANDARD (up to 5 retries)
  • Plan: Scale
  • Failover destination: Email

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

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

Related guides

← Back to documentation