Retries and Delivery Behavior

Use this guide to configure retries correctly and interpret delivery behavior.

Purpose

This guide covers:

• Per-output retry configuration for webhooks.
• Automatic retry behavior for Slack, Discord, email, and Google Sheets targets.
• Plan-based retry caps for webhooks.
• Activity outcomes tied to failed deliveries.
• Idempotency guidance for receivers.

How retries work

Retries are configured per output, not per endpoint.

Webhook targets

• Delivery retries is set individually on each webhook output in the Target destination tab.
• Uses exponential backoff according to the selected retry preset.
• Default is 0 (no retries).
• Effective retries are capped by your plan tier.

Plan caps for webhooks:

If a webhook's retry count exceeds the plan cap, the API rejects the configuration.

The webhook retry schedule depends on the retry preset chosen for each output. See Webhook Retry Presets for full details.

Default preset (STANDARD) schedule:

Only as many delays as needed are used based on the configured retry count. Other presets (AGGRESSIVE, CONSERVATIVE) use different schedules and require Pro or higher tier.

Slack and Discord targets

Slack and Discord targets automatically retry 5 times with a fast backoff schedule. This is not user-configurable.

Email and Google Sheets targets

Email targets automatically retry up to 5 times using the same backoff schedule as the STANDARD webhook preset. Google Sheets retries transient failures on the same backoff buckets until the message is older than 24 hours. These settings are not user-configurable.

Email retries apply to transient/provider failures; permanent SMTP failures such as authentication errors and SMTP 5xx recipient rejections fail immediately. Google Sheets retries apply only to retryable failures (rate limits, server errors, and connection errors). A non-retryable error such as a 400 or 403 response from the Google Sheets API will not be retried.

Failover behavior

Failover provides a backup delivery path when your primary webhook target is unavailable. It is available on webhook outputs only.

How failover works

1. The primary webhook output attempts delivery (including all configured retries).
2. If all retries are exhausted and the delivery still fails, PayloadRelay dispatches the request to the configured failover target.
3. The failover delivery is logged with outcome FAILOVER_TRIGGERED in Activity.
4. If the failover target is itself a webhook, it has its own independent retry setting. Supported non-webhook failover targets (email, Slack, Discord) use their standard automatic retry schedules.

Configuring failover

1. Open the endpoint edit page and go to the Target destinations tab.
2. Expand the webhook output you want a failover for.
3. Check Enable failover delivery.
4. Select a failover target from the dropdown. Supported failover delivery targets are webhook, email, Slack, and Discord. Google Sheets targets are not supported for failover.
5. Configure the failover target's own output settings (email subject, Slack markdown, etc.) if needed.
6. Save the endpoint.

Failover behavior notes

• Failover activates only after all primary retries are exhausted. If you set 0 retries on the webhook, failover triggers immediately on the first failure.
• The FAILOVER_TRIGGERED outcome is logged separately from the primary delivery attempt, so you can see both in Activity.
• If both the primary and the failover target fail, no further fallback occurs — the overall outcome remains DELIVERY_FAILED.
• Test deliveries (from the Send test button) never trigger failover. Failover is a production-only mechanism.

Incoming request
       │
       ▼
  Primary webhook target → fails after 3 retries
       │
       ▼
  Email failover target → delivers to [email protected]

This pattern is common for alerting — try the real-time webhook first, and if it's down, send an email so no event is lost.

Incoming request
       │
       ▼
  Primary webhook (api.example.com) → fails after retries
       │
       ▼
  Failover webhook (backup.example.com) → has its own 2 retries

Use this when both destinations are webhooks and you want the failover to also retry independently.

Prerequisites and permissions

• Endpoint edit access.
• Billing page access to check plan limits.
• Activity access for monitoring outcomes.

Step-by-step workflow

1. Confirm plan retry cap

1. Open Billing.
2. Check the delivery retry cap for your tier.

2. Configure webhook retries

1. Open endpoint edit page.
2. Go to the Target destination tab.
3. For each webhook output, set Delivery retries within plan range.
4. Save.

Non-webhook targets (email, Slack, Discord, Google Sheets) automatically retry and do not have a configurable retry setting.

3. Monitor outcomes

In Request activity, monitor for:

• DELIVERY_FAILED (delivery failed after all retries)
• FAILOVER_TRIGGERED (failover target was activated after primary webhook exhausted retries)
• TEST_REJECTED / TEST_RATE_LIMITED (target-test-only outcomes)

4. Make downstream handling idempotent

Receivers should tolerate repeated deliveries:

• Deduplicate on stable event identifiers when available.
• Make writes idempotent.
• Avoid side effects that fail on replays.

Expected result and verification checks

• Webhook retry settings match plan constraints.
• Non-webhook targets retry automatically without configuration.
• Delivery failures are visible and actionable in Activity.
• Failover triggers are logged with FAILOVER_TRIGGERED outcome.
• Downstream systems process repeated deliveries safely.

Common issues and fixes

• Retry value rejected: reduce value to plan max.
• Frequent DELIVERY_FAILED: validate destination auth, connectivity, TLS.
• Unexpected duplicates downstream: add idempotency controls.
• Failover not triggering: ensure Delivery retries is configured on the webhook (failover activates after retries are exhausted).

Related guides

• Relay Targets
• Billing and Usage
• Observability
• Troubleshooting
• Incident Response