Understanding Automated Webhook Retries for Marketplace Apps
Overview
To enhance the reliability of data delivery, the CRM includes an automated system for retrying webhook calls from Marketplace apps. This feature is designed to handle temporary rate limits gracefully, ensuring that important events are not lost due to brief periods of high traffic on your server.
The system specifically targets HTTP 429 (Too Many Requests) responses. When your endpoint returns this status code, the CRM will automatically attempt to resend the webhook payload. All other HTTP status codes, including successful responses (2xx) and other errors (4xx or 5xx), are treated as final, and no further retries will be made for that specific webhook event.
How It Works
Retry Conditions
The automated retry logic is intentionally precise to provide predictable behavior.
- Retry Trigger: The system will only retry a webhook if your server responds with an HTTP 429 status code.
- Stop Conditions: Any other status code, whether it indicates success (like 200) or a different type of error (like 404 or 500), will cause the system to stop retrying that particular webhook delivery.
Retry Schedule
When a 429 response is received, the CRM will make up to six additional attempts to deliver the webhook.
- Interval: Each retry attempt occurs approximately 10 minutes after the previous one.
- Jitter: A small, randomized delay (jitter) is added to each 10-minute interval. This prevents a large number of retries from happening simultaneously, which could overwhelm your server and cause further rate limiting.
- Maximum Duration: The entire retry process, from the first failure to the final attempt, spans roughly 1 hour and 10 minutes.
Key Benefits
- Improved Reliability: Temporary spikes in traffic that cause rate limits no longer result in lost data.
- Predictable Load: The fixed interval and jitter prevent sudden surges of retry traffic, protecting your server infrastructure.
- Developer Control: You have full control. By returning any status code other than 429, you can immediately signal that no further retries are necessary.
Best Practices for Developers
To work effectively with this system, structure your endpoint's responses appropriately.
- Return a 200 OK status code to acknowledge successful receipt of a webhook, even if you plan to process the data asynchronously.
- Only return a 429 Too Many Requests status when your server is genuinely at capacity and needs the CRM to slow down its delivery attempts.
- For other errors, such as a 5xx Server Error, return the appropriate code. The CRM will treat this as a permanent failure and will not retry, preventing unnecessary load on a malfunctioning endpoint.
Frequently Asked Questions
Can I customize the number of retries or the interval?
No. The retry schedule—six attempts with a 10-minute interval—is a fixed system setting and cannot be customized.
How can I test the retry behavior?
You can test this feature by configuring a test endpoint that returns a 429 status code. You should then observe the CRM resending the webhook payload up to six times over a period of about 70 minutes.
What if my endpoint returns a 404 or 400 error?
Any non-429 response, including 404 (Not Found) or 400 (Bad Request), is considered a final delivery attempt. The CRM will not retry the webhook.
Does the system handle duplicate events?
Yes. Each delivery attempt for the same webhook event will include the same unique delivery identifier. You can use this to detect and safely ignore any duplicate payloads.