Retry mechanism

Our webhook system is designed to ensure you receive all your messages, even if temporary issues prevent immediate delivery. To achieve this, we’ve implemented a retry mechanism that resends messages if they don’t get through on the first attempt. Importantly, retries are handled on a per-message basis, meaning each webhook message follows its own independent retry schedule. This ensures that the failure of one message doesn’t affect the delivery attempts of others.

This guide will walk you through how the retry mechanism works, the differences between free and paid tier users, and practical steps you can take to ensure your system handles webhooks effectively.

​

How it works

When we send a webhook message to your server, we expect a 200 status code within 10 seconds to confirm successful receipt. Your server should return this response immediately and process the message afterward. Processing the message before sending the response can lead to timeouts and trigger unnecessary retries.

• Attempt 1: We send the message expecting a respose with 200 status code. If we do not receive a 200 status code within 10 seconds, the attempt is considered failed. During this window, any non-2xx responses are ignored.
• Attempt 2: Occurs 10 seconds after the first attempt, with another 10-second timeout and the same rule for ignoring non-2xx responses.
• Retry Queue After Two Failed Attempts If both initial attempts fail, the message enters a retry queue with progressively longer intervals between attempts. Each retry attempt still has a 10-second timeout, and non-2xx responses are ignored during this window.

The retry schedule is as follows:

Total Retry Duration: Up to approximately 44.8 hours (2,688 minutes) if all retries are exhausted.

Interval Timing: Each retry interval starts 10 seconds after the previous attempt is deemed failed. For example, if attempt 2 fails at t=20 seconds, attempt 3 will start at t=80 seconds (20s + 1 minute interval + 10s).

​

Differences Between Free and Paid Tier Users

The behavior of the retry mechanism varies based on your subscription tier: Free tier users

• Initial attempts limit: If six messages fail both the first and second attempts, your webhook will be automatically deactivated.
• Retry queue limit: Only five messages can enter the retry queue over the lifetime of the subscription. If a sixth message requires retry queuing, or if any message fails all 10 retry attempts, the subscription will be deactivated.

Paid tier users

• For paid users, webhooks will be deactivated if a single message, retried at the 24-hour interval, fails to process successfully.

​

What you can do

Ensure server availability:

• Keep your server running smoothly to receive webhook messages without interruption.
• Implement logging for incoming webhook requests and your server’s responses to help identify any issues quickly.

Design for idempotency

• Set up your webhook handler so it can safely process the same message multiple times without causing errors or unwanted effects. This way, if retries occur, they won’t negatively impact your system.
• The webhook retry mechanism is designed to maximize the reliability of message delivery while minimizing the impact of temporary issues. By understanding how retries work—especially the per-message nature of the system—and following best practices like ensuring server availability and designing for idempotency, you can ensure a seamless experience with webhooks.

​

Key Takeaways

• Each message has its own retry schedule, ensuring isolation and reliability.
• Free tier users have limits on failed attempts and retry queue entries, while paid users do not.
• Implement logging and idempotency to handle retries effectively and avoid disruptions.
• By following this guide, you’ll be well-equipped to manage webhooks and ensure your system remains robust, even in the face of temporary challenges.