Skip to main content

​
Retry Policy

At-least-once delivery: Paxos delivers webhook events with at-least-once semantics. Because retries can cause the same event to be delivered more than once, your consumer must be idempotent. Deduplicate on the event id so that processing the same event multiple times has no additional effect.
If your webhook consumer endpoint fails to accept a delivery or returns a retriable error status (anything other than a 2xx response), Paxos will automatically attempt to retry the webhook delivery.

​
Retry Schedule

We use an exponential backoff policy with jitter (randomization to avoid retry storms) with the following schedule:
  • Initial retry delay: ~5 seconds after initial failure
  • Subsequent retries: Increasing intervals with exponential backoff
  • Maximum retry duration: 24 hours from the time the event was first invoked
Paxos will continue retry attempts for up to 24 hours from the initial attempt, unless delivery succeeds. After this period, no additional retry attempts will be made.

​
Handling Failed Deliveries

After the 24-hour retry window has elapsed, undelivered events will not be automatically retried. To recover these undelivered events, you can:
  1. Use the List Events API to query for events that may have failed delivery
  2. Use the event IDs to fetch the full event details via the Events API
  3. Process these events through your regular webhook handling logic

​
Rate Limits

To ensure optimal performance and stability, Paxos implements rate limits on webhook deliveries. When configuring a webhook via the Dashboard, you can set the rate limit from 1 to 100 requests per second. The default is 10 requests per second.

​
Best Practices

For optimal webhook processing, we recommend:
  1. Respond quickly: Your webhook endpoint should acknowledge receipt with a 2xx status code as quickly as possible (ideally < 500ms)
  2. Process asynchronously: Acknowledge the webhook immediately, then process the event asynchronously in your application
  3. Implement idempotency: Design your webhook handlers to be idempotent in case the same event is delivered multiple times
  4. Monitor delivery failures: Implement monitoring for webhook delivery failures to detect issues early
  5. Implement backup polling: Establish a periodic job that polls the Events API as a fallback mechanism for missed webhook events
  6. Ignore test events: You may wish to test the functionality of your webhook consumer endpoint by sending test events. To ignore test events, you can filter on the is_test=false field in your webhook consumer.