Zquence retries failed webhook deliveries with exponential backoff. A delivery attempt is considered successful only when your endpoint returns a 2xx response within the request timeout.
Request timeout
Each webhook request has a 10 second timeout.
If your endpoint does not complete inside that window, the attempt is marked failed.
Default retry schedule
The current default environment setting is:
DEFAULT_WEBHOOK_RETRIES = 3
That means the default total delivery plan is:
| Attempt | Timing |
|---|
| 1 | Immediate |
| 2 | 2 seconds later |
| 3 | 4 seconds later |
| 4 | 8 seconds later |
Environment-specific retry counts
If an environment defines webhookRetries, total attempts become:
maxAttempts = webhookRetries + 1
Retry delay uses this formula:
delaySeconds = 2 ^ (nextAttempt - 1)
What counts as success?
Any 2xx response:
200 OK
201 Created
202 Accepted
204 No Content
What counts as failure?
Any of the following marks the attempt as failed:
4xx response (except 429) — permanent failure, no retry
5xx response — retryable failure
429 response — retryable failure
- connection failure — retryable
- DNS failure — retryable
- TLS failure — retryable
- timeout after 10 seconds — retryable
Important behavior: 4xx responses are permanent failures
4xx responses (except 429) are treated as permanent failures and are never retried.
The complete breakdown:
| Response | Retried? | Notes |
|---|
2xx | No — success | Delivery stops immediately |
4xx (not 429) | No — permanent failure | Attempt budget is exhausted immediately |
429 Too Many Requests | Yes | Treated the same as 5xx |
5xx | Yes | Retried until budget exhausted |
| Timeout / network error | Yes | Retried until budget exhausted |
This means if your endpoint rejects a delivery with 400, 401, 403, 404, 422, or any other 4xx (except 429), Zquence stops retrying immediately. No further attempts are made for that delivery.
Do not return a 4xx response to signal a transient error. Use 5xx for errors you expect to resolve (downstream service unavailable, temporary processing failure). Reserve 4xx for permanent rejections only.
Delivery logs
Every attempt is stored in the delivery log with fields such as:
eventId
eventType
endpointId
endpointUrl
attempt
status
statusCode
error
responseBody
deliveredAt
API-only sync
Delivery logs are created for endpoint delivery attempts. If a tenant has no matching
webhook endpoint, has webhook delivery disabled, or chooses to rely on APIs only, use
List sync events instead.
Sync events are recorded before endpoint matching and delivery decisions. Poll this API
with the sync.read scope to catch up on missed or undelivered events, then deduplicate
by eventId or payload.id.
Manual replay
Stored deliveries can be replayed manually from the dashboard. Public API-key replay
endpoints are not exposed yet.
Current rules:
- the log entry must exist
- the endpoint must still exist
- the endpoint must still be
active
When replayed manually, the stored event is queued again as a new attempt.
This mechanism is designed for operational resync scenarios, including:
- downstream receiver outages
- delayed ingestion on the tenant side
- partial data loss in the receiving system
- controlled replay of a known event window
Manual replay sends the stored webhook payload to the configured endpoint again. It does not modify historical data inside Zquence.
Filtered manual replay
In addition to replaying one delivery at a time, Zquence supports filtered manual replay
from the dashboard. Use this when you want to replay only a subset of webhook events
instead of replaying every stored row.
Example filter:
{
"environmentId": "69f9b5fa0600ccbf9c677005",
"endpointId": "6843d05008fdff9db4000001",
"eventType": "account.created",
"status": "success",
"dateFrom": "2026-06-01T00:00:00.000Z",
"dateTo": "2026-06-07T23:59:59.000Z",
"limit": 100
}
Example cURL:
curl -X POST https://api.example.com/v1/webhooks/deliveries/retry \
-H "Content-Type: application/json" \
-H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
-H "x-api-secret: $ZQUENCE_SECRET_KEY" \
-d '{
"environmentId": "69f9b5fa0600ccbf9c677005",
"eventType": "account.created",
"status": "success",
"dateFrom": "2026-06-01T00:00:00.000Z",
"dateTo": "2026-06-07T23:59:59.000Z",
"limit": 100
}'
Supported filters
- tenant
- environment
- endpoint
- event type
- status
- date range
How it works
- Filters narrow the delivery-log set before replay.
- If you provide a status filter, only that delivery state is replayed.
- If you do not provide a status filter, any matching delivery state can be replayed.
- Zquence deduplicates by
endpointId + eventId, so repeated logged attempts for the same event are only queued once.
- Deleted or disabled endpoints are skipped and reported in the response summary.
- Replayed events are signed again with the endpoint’s current signing secret.
What replay does and does not do
Replay does:
- re-send the stored webhook event to the tenant’s configured endpoint
- preserve the existing event envelope and signing model
- allow targeted recovery for specific event types and time windows
Replay does not:
- update historical records inside Zquence
- bypass endpoint status checks
- send to deleted or disabled endpoints
Response summary
Filtered replay returns a summary including:
matched
queued
skipped
- per-item results for skipped deliveries such as
endpoint_not_found or endpoint_disabled
Recommended receiver behavior
- Return
200 after verification and queueing.
- Do not do long-running work before responding.
- Deduplicate by
event.id.
- Log failures on your side together with
event.id and X-Zquence-Webhook-Id.