Reliability
Retries & idempotency
Understand retry schedules, idempotency keys, dead-letter handling, and how to replay failed deliveries after fixing a destination.
Failed deliveries retry automatically with exponential backoff. Retries use the same delivery ID, so your destination can safely deduplicate them.
Default retry schedule
Section titled “Default retry schedule”Each destination can override the policy field by field; agent targets ship different defaults.
| Target | Max attempts | Initial delay | Max delay | Backoff |
|---|---|---|---|---|
http (generic), slack |
5 | 2s | 300s | exponential, ±20% jitter |
grokbot, t3code, paseo (agent targets) |
3 | 15s | 120s | exponential, ±20% jitter |
For the generic HTTP default, attempts run at roughly:
| Attempt | Timing |
|---|---|
| 1 | Immediately after fan-out. |
| 2 | About 2 seconds later, after a timeout or 5xx. |
| 3 | About 4 seconds after attempt 2. |
| 4 | About 8 seconds after attempt 3. |
| 5 | About 16 seconds after attempt 4, then dead. |
Delays double each attempt and are capped at the policy’s max delay (300s by default). Jitter is ±20%, so these are approximate. Retry-After is honored for 429 and 503 responses and capped at 15 minutes. A destination retryPolicy can change maxAttempts (1–10), backoff, initial delay and max delay within the ranges on Limits.
When a retryable failure runs out of attempts the delivery becomes dead (a dead letter); a permanent failure (4xx other than 408, 425 and 429) becomes failed immediately. Both are terminal, both can be retried manually, and a manual retry grants one extra attempt. Dead-letter email is off by default; enable it under Settings → Workspace → Dead-letter email.
Deduplicate at the destination
Section titled “Deduplicate at the destination”Store X-Hooks-Delivery in a unique index before processing. If the same ID arrives again, return 200 without repeating side effects. A 2xx response stops retries immediately.
Rate limits and timeouts also trigger retries. Return a 4xx only when retrying cannot help — for example, a malformed payload or an unknown account.
Manual retry and replay
Section titled “Manual retry and replay”POST /v1/deliveries/{id}/retryre-queues a failed or stuck delivery.POST /v1/events/{id}/replayreplays an event to its destinations.POST /v1/deliveries/{id}/cancelcancels a queued delivery.POST /v1/deliveries/bulk-cancelcancels every pending, queued or retrying delivery that matches a filter.
Bulk cancel queued deliveries
Section titled “Bulk cancel queued deliveries”When a destination is misconfigured, queued deliveries pile up. Bulk cancel clears them without touching deliveries that already succeeded or failed.
# Preview: count matches, create nothingcurl -X POST "https://api.hooks.events/v1/deliveries/bulk-cancel" \ -H "Authorization: Bearer $HOOKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"filters":{"destinationId":"dst_123","status":"retry_wait"},"dryRun":true}'
# Start the jobcurl -X POST "https://api.hooks.events/v1/deliveries/bulk-cancel" \ -H "Authorization: Bearer $HOOKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"filters":{"destinationId":"dst_123"}}'Filters accept destinationId, endpointId, status (one of pending, queued, retry_wait), since and until (ISO 8601, applied to the delivery creation time). With no status, every cancellable status matches. Only those three statuses can ever be cancelled; delivering, succeeded, failed and dead deliveries are left alone.
The response is a job with total and cancelled. Read progress with GET /v1/deliveries/bulk-cancel/{id}; the job reaches completed when nothing matching is left. POST /v1/deliveries/bulk-cancel/{id}/cancel stops a running job — batches already in flight finish, later batches are dropped. The console exposes the same flow through the Cancel queued button on the Deliveries page, which scopes the job to the filters currently selected there.
Only replay events when the destination state is known to be safe; a replay creates new delivery attempts against the same destinations.