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, Microsoft Teams, PagerDuty, Telegram, and Google Sheets targets.
• Plan-based retry caps for all delivery types.
• 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 destinations tab.
• Uses the fixed schedule from the selected retry preset.
• Default is 0 (no retries).
• Effective retries are capped by your plan tier.

Plan retry caps:

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. Sandbox and Solo use STANDARD with the default retry status codes. Team trial, Team, Scale, and Unlimited may choose advanced presets or custom status-code filters.

Slack and Discord targets

Slack and Discord targets use a fast automatic retry schedule capped by your plan. This is not user-configurable. Sandbox uses the first bucket, Solo uses the first 3, and Team trial, Team, and Scale use all 5.

Email, Microsoft Teams, PagerDuty, and Telegram targets

Email, Microsoft Teams, PagerDuty, and Telegram targets use the same automatic backoff buckets as the STANDARD webhook preset, capped by your plan. These settings are not user-configurable. Sandbox uses the first bucket, Solo uses the first 3, and Team trial, Team, and Scale use all 5.

Email retries apply to transient/provider failures; permanent SMTP failures such as authentication errors and SMTP 5xx recipient rejections fail immediately. Microsoft Teams, PagerDuty, and Telegram retries apply to network errors, HTTP 408, HTTP 429, and 5xx responses.

Google Sheets targets

Google Sheets retries transient failures on the same backoff buckets, capped by your plan and by the 24-hour message age limit. These settings are not user-configurable. Sandbox uses the first bucket, Solo uses the first 3, and Team trial, Team, and Scale use all 5.

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 output 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 destination.
3. The failover delivery is logged with outcome FAILOVER_TRIGGERED in Activity.
4. If the failover destination is itself a webhook output, it has its own independent retry setting. Supported non-webhook failover destinations (email, Slack, Discord, Microsoft Teams) use their standard automatic retry schedules capped by your plan.

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 destination from the dropdown. Supported failover delivery destinations are webhook, email, Slack, Discord, and Microsoft Teams. Google Sheets, PagerDuty, and Telegram targets are not supported for failover.
5. Configure the failover delivery 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 delivery 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 output → fails after 3 retries
       │
       ▼
  Email failover destination → delivers to ops@example.com

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 output (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 destinations tab.
3. For each webhook output, set Delivery retries within plan range.
4. Save.

Targets without user-configurable retry settings (email, Slack, Discord, Microsoft Teams, PagerDuty, Telegram, and Google Sheets) automatically retry where supported, capped by your plan.

Retries, failover, and fan-out never consume additional accepted-event quota.

3. Monitor outcomes

In Request activity, monitor for:

• DELIVERY_FAILED (delivery failed after all retries)
• FAILOVER_TRIGGERED (failover destination 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 failover is enabled on the webhook output, the request is production traffic (not Send test), and the primary delivery has failed or exhausted its configured retries.

Related guides

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