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:
AttemptTiming
1Immediate
22 seconds later
34 seconds later
48 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:
  • non-2xx response
  • connection failure
  • DNS failure
  • TLS failure
  • timeout after 10 seconds

​
Important behavior: all non-2xx responses retry

Current implementation retries every non-2xx response while attempts remain. So the following all count as retryable failed attempts:
  • 400
  • 401
  • 403
  • 404
  • 409
  • 422
  • 429
  • 500
  • 503
If you intentionally reject a request because the secret is wrong or the signature is invalid, it will still appear as a failed delivery and may retry until the attempt budget is exhausted.

​
Delivery logs

Every attempt is stored in the delivery log with fields such as:
  • eventId
  • eventType
  • endpointId
  • endpointUrl
  • attempt
  • status
  • statusCode
  • error
  • responseBody
  • deliveredAt

​
Manual replay

Stored deliveries can be replayed manually.

​
Replay endpoints

PurposeMethodEndpoint
Replay one stored deliveryPOST/webhooks/deliveries/:id/retry
Replay multiple stored deliveries by filterPOST/webhooks/deliveries/retry
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. Use this when you want to replay only a subset of webhook events instead of replaying every stored row. Example request: 
{
  "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 "Authorization: Bearer <token>" \
  -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

​
Tenant access behavior

  • Tenant users can replay only their own tenant’s webhook deliveries.
  • This makes the endpoint suitable for a self-service Resync webhooks action inside a tenant portal.
  • Superadmin or internal tooling may replay on behalf of a tenant when broader operational support is required.

​
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
  • 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.