Webhook Retry Strategy

Retry And Replay Paths

There are three retry paths in FastHook. They all produce auditable request, event, and attempt records, but they happen at different points in the delivery model.

• Automatic retry: a connection rule schedules another delivery attempt after an outbound destination failure.
• Request retry: FastHook replays the original inbound request through the source pipeline, current routing, filters, transformations, deduplication, and pause state.
• Event retry: FastHook retries one existing outbound event branch for the same source, connection, and destination path.
• Bulk retry: FastHook creates a batch operation from filters and queues request retries or event retries for the selected records.
• Provider retry: the external provider sends the webhook again. Treat this as separate from FastHook retry and keep receivers idempotent.

Provider retry
  -> provider sends the webhook again

FastHook request retry
  -> original request runs through current routing again

FastHook event retry
  -> one existing destination branch is queued again

Automatic connection retry
  -> failed destination delivery is scheduled by retry rule

Automatic Retry Rules

A retry rule belongs to a connection. It decides how many retry attempts FastHook may schedule after the first delivery attempt fails and how long to wait between attempts.

If a connection has no retry rule, a destination HTTP error or transport error marks the event failed. Internal queue and database transient retries are separate worker safeguards and are not a substitute for a user-configured delivery retry policy.

• count is the number of retry attempts after the first delivery attempt, not the total number of attempts.
• strategy can be linear or exponential.
• interval is the base delay in milliseconds. If interval is missing or zero, FastHook falls back to a short one-second delay.
• response_status_codes controls which HTTP statuses are retried. Transport errors can be retried by the rule because there is no HTTP status to match.
• While waiting for a retry delay, the event is SCHEDULED.

{
  "type": "retry",
  "strategy": "exponential",
  "interval": 30000,
  "count": 3,
  "response_status_codes": ["429", "500-599"]
}

Status Code Matching

Retry status rules should match failures that can recover. A receiver returning 429 or 503 usually deserves another attempt. A receiver returning a permanent validation error usually needs a payload or destination fix instead.

• Use exact codes such as 429 or 503 for known recoverable responses.
• Use ranges such as 500-599 for temporary server failures.
• Use comparisons such as >=500 when a range is easier to read.
• Avoid retrying broad 4xx ranges unless the receiver intentionally uses them for temporary throttling.
• If response_status_codes is omitted, the retry rule can retry any failed HTTP status.

["429", "500-599"]
[">=500"]
["503", "504"]

Request Retry

Request retry replays a previously received request from the source side. FastHook queues the stored payload back into ingestion as retry traffic, then evaluates current routing, filters, transformations, deduplication, connection state, and pause state.

Use request retry when routing has changed, a filter was fixed, a transformation was updated, or the original request was rejected and should be processed again after a source-level fix.

• The source must be enabled.
• The original request payload must still be available.
• The new replay request is marked with is_retry and retry_kind.
• Because current routing is evaluated again, request retry can create a different set of events than the original request.

fasthook requests retry req_xxx

curl -X POST "https://api.fasthook.io/v1/requests/req_xxx/retry" \
  -H "Authorization: Bearer fhp_xxx"

Event Retry

Event retry targets one existing outbound event branch. It is the safest choice when a specific destination failed but the original source request and routing decision were correct.

Event retry does not bypass operational controls. The source must be enabled, the connection must be enabled, and the connection must not be paused.

• Use event retry when one destination branch failed in a fan-out topology.
• A paused connection returns a conflict instead of silently sending around pause controls.
• A disabled connection or disabled source must be enabled before event retry can queue.
• The retry creates a new replay event id and attempts show trigger MANUAL for single event retry.

fasthook events retry evt_xxx

curl -X POST "https://api.fasthook.io/v1/events/evt_xxx/retry" \
  -H "Authorization: Bearer fhp_xxx"

Bulk Retry

Bulk retry creates a batch operation from filters. Use it after an incident when many requests or events need the same recovery action.

Keep bulk retry filters narrow. Select by time range, source, destination, connection, status, and search term so the operation only replays traffic that actually needs recovery.

• Request bulk retry replays selected requests through current routing.
• Event bulk retry retries selected existing event branches.
• Bulk operations can be listed, watched, and cancelled while they are planned or running.
• Event bulk retry marks items failed when the source is disabled, the connection is disabled, the connection is paused, or payload data is missing.

# request bulk retry: run selected source requests through current routing
{
  "from": "2026-05-25T10:00:00.000Z",
  "to": "2026-05-25T10:30:00.000Z",
  "status": "accepted",
  "source_id": "src_xxx"
}

fasthook requests bulk-operations create --json-file request-retry.json

# event bulk retry: retry failed events for one destination branch
{
  "from": "2026-05-25T10:00:00.000Z",
  "to": "2026-05-25T10:30:00.000Z",
  "status": "FAILED",
  "destination_id": "des_xxx"
}

fasthook events bulk-operations create --json-file event-retry.json

Statuses And Attempts

Retries are visible in event status and attempt records. Use events to see where work is waiting, and attempts to see the exact receiver response that caused the retry or failure.

• QUEUED means delivery work is waiting to be sent.
• SCHEDULED means delivery is waiting on retry backoff, a delay rule, destination rate limiting, or another scheduled delivery path.
• HOLD means the connection is paused and new routed events are being held.
• FAILED means retry rules were exhausted, no retry rule matched, or delivery failed without a retry path.
• Attempts include trigger values such as INITIAL, AUTOMATIC, MANUAL, BULK_RETRY, and UNPAUSE.

Pause, Disable, And Retry

Pause and disable are different recovery controls. Pause holds new routed events for a connection. Disable stops a route from receiving future events. Retries should respect both choices.

• Use pause when the source should keep accepting traffic but one destination branch should wait.
• Use disable when the branch should stop receiving future routed events.
• Resume a paused connection before retrying failed events for that route.
• Use a destination throughput limit before unpausing or bulk retrying a large failed window.
• Watch event metrics for failed, scheduled, queued, and held counts while the route drains.

Idempotent Receivers

Any system that receives webhook retries should handle duplicate deliveries. Provider retries, FastHook automatic retries, manual event retries, request replays, and bulk operations can all deliver the same business event more than once.

• Store a provider event id when the provider offers one.
• Store a FastHook event id or business id when provider ids are not enough.
• Return 2xx only after the receiver has durably accepted the work.
• Treat repeated deliveries as safe no-ops when the work has already completed.
• Keep deduplication rules and receiver idempotency separate: FastHook deduplication can reduce duplicate delivery, but receivers still need their own guards.

Recovery Workflow

During an outage, start by identifying whether traffic is missing at ingress, stuck in routing, or failing at a destination. Then choose the smallest retry path that fixes the affected traffic.

• If FastHook never received the provider request, fix provider configuration first.
• If the source rejected traffic, inspect source verification and retry the request after the fix.
• If one destination failed, retry events for that destination branch.
• If routing or filters changed, retry requests so current routing runs again.
• If many records failed, create a bulk operation from a narrow filter.

# 1. Check the shape of the incident
fasthook metrics requests --source_id src_xxx --from 2026-05-25T10:00:00Z --to 2026-05-25T10:30:00Z
fasthook metrics events --destination_id des_xxx --from 2026-05-25T10:00:00Z --to 2026-05-25T10:30:00Z

# 2. Inspect failed events and attempts
fasthook events list --destination_id des_xxx --status FAILED --limit 50
fasthook attempts list --event_id evt_xxx

# 3. Retry the smallest safe slice
fasthook events retry evt_xxx

Next

• Control throughput
• Deduplication patterns
• Metrics
• API reference