Delivery & Reliability

Revaly webhooks use an at-least-once delivery model to maximize delivery reliability. This means webhook events may occasionally be delivered more than once, and integrations should be designed to safely handle duplicate deliveries.

This guide explains how webhook deliveries are processed, when retries occur, how duplicate events should be handled, and what happens when an endpoint becomes unavailable.

Delivery Outcomes

A webhook delivery is considered successful when your endpoint returns a 2xx response. Once a successful response is received, no further delivery attempts are made.

Revaly waits up to 30 seconds for a response. If the endpoint does not respond within that time, the delivery is considered failed and becomes eligible for retry.

Revaly retries deliveries when transient failures occur.

Response	Retry?
2xx	No
429	Yes
5xx	Yes
Timeout	Yes
Connection Failure	Yes
Other 4xx	No

Client errors generally indicate a permanent problem and are not retried.

Retry Schedule

Retry delays increase over time to reduce pressure on unavailable endpoints while still maximizing the likelihood of successful delivery.

Attempt	Delay
1	Immediate
2	30 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	6 hours
7	24 hours

Retry delays include a small amount of randomization to prevent large numbers of events from being retried simultaneously. After all retry attempts have been exhausted, the event is no longer automatically retried.

Handling Duplicate Deliveries

Because Revaly uses an at-least-once delivery model, duplicate deliveries are expected under certain conditions.

Timeouts
Network interruptions
Retryable responses
Processing delays
Connection failures

To prevent duplicate processing, use the event id for deduplication. The event ID remains constant across retries, while a new deliveryId is generated for each delivery attempt.

{
  "id": "evt_01JSZK9ABC...",
  "deliveryId": "dlv_..."
}js

Endpoint Health

If an endpoint repeatedly fails deliveries, Revaly may temporarily pause new deliveries until the endpoint becomes healthy again. This helps prevent continuous delivery failures and allows merchants time to correct the underlying issue.

If your endpoint enters a held state, contact Revaly Support for assistance validating and restoring delivery.

Event Replay

Revaly does not currently provide:

Event replay APIs
Event resend APIs
Bulk replay operations
Self-service redelivery tools

If an event requires manual replay after exhausting the retry schedule, contact Revaly Support.

Recommended Practices

The following recommendations can help improve webhook reliability and reduce the likelihood of duplicate processing or failed deliveries.

Return 2xx responses as quickly as possible
Perform business logic asynchronously
Deduplicate using the event ID
Store events before processing
Monitor delivery failures and timeouts
Log event IDs and delivery IDs
Handle unknown event types gracefully