Automated Webhook Retries for SourCherry Marketplace apps guarantee that critical events reach your serversâeven when you hit temporary rate limitsâby retrying only HTTP 429 responses and adding randomized jitter. This guide shows Marketplace developers how the new system works and how to prepare your endpoints for flawless delivery.
This is the Webhook Integration Guide.
TABLE OF CONTENTS
- What is Marketplace Automated Webhook Retries?
- Key Benefits of Marketplace Automated Webhook Retries
- Retry Schedule
- Retry Conditions
- Jitter Protection
- How to use it as a Developer?
- Recommended HTTP Response Codes
- Frequently Asked Questions
What is Marketplace Automated Webhook Retries?
SourCherryâs Marketplace now includes a built-in, intelligent retry mechanism for outbound webhooks. When your appâs endpoint responds with HTTP 429 (Too Many Requests), SourCherry will automatically re-send the same payload up to six times on a spaced-out schedule with randomized jitter. All other status codes (2xx success, 4xx/5xx errors) are treated as final, giving you predictable delivery behavior and preventing server overload.
- Retries only on HTTP 429s: We now retry webhook deliveries only when your endpoint returns a 429 (rate limit) response.
- Jitter protection: Randomized retry timing prevents the âthundering herdâ problem and spreads load evenly across servers.
Key Benefits of Marketplace Automated Webhook Retries
- Reliability â transient rate-limit spikes no longer cause lost events.
- Predictability â a fixed 10-minute interval (plus jitter) and six-attempt cap lets you model worst-case latency (~1 hr 10 min).
- Server Protection â jitter prevents a âthundering herdâ of simultaneous retries, spreading load evenly across your infrastructure.
- Developer Control â by returning any status other than 429 you can immediately stop further retries.
Retry Schedule
Every retry happens 10 minutes after the previous attempt, but each interval is randomized by a small, pseudo-random offset (jitter) to avoid synchronized traffic bursts. The system stops after six retries or any non-429 response, whichever comes first. Total possible retry window: approximately 1 hour 10 minutes.
- Interval: 10 minutes between retries (with jitter)
- Max attempts: 6 retries
- Total retry duration: ~1 hour 10 minutes
Retry Schedule for Non-429 Failures
Non-429 webhook failures now follow an exponential backoff retry strategy instead of the fixed retry interval used for HTTP 429 responses.
For non-429 failures, retries can continue for up to 3 days. This helps improve delivery reliability when endpoints are temporarily unavailable, timing out, or returning intermittent server errors.
Retry Conditions
The retry logic is intentionally narrow so developers always know what to expect.
- Retried Status Code: 429 only.
- Stop Conditions: any other status (200, 202, 204, 4xx, 5xx, etc.).
- No Retries on 5xx: server-side failures are treated as permanent to avoid hammering a downed endpoint.
- We do not retry on 5xx server errors â those are treated as permanent failures.
Retry Conditions for HTTP 429 vs Other Failures
Retry behavior now depends on the type of failure returned by the webhook endpoint.
- HTTP 429 responses continue using the existing retry behavior with a fixed 10-minute interval for approximately 1 hour.
- Other webhook failures now also retry, including temporary endpoint downtime, server errors, timeouts, and transient network issues.
This improves reliability for failures beyond rate limiting while preserving the existing handling for 429 responses.
Jitter Protection
Randomized jitter (± N seconds) is applied to each 10-minute interval. This tiny variation ensures that if multiple events were throttled at once, their retries wonât all fire in the same instantâdramatically reducing the risk of cascading rate-limit hits across your fleet.
How to use it as a Developer?
Hereâs how you can make the most of this system:
â
Return 200 OK for successful deliveries.
â
Even if processing fails internally, still return 200 OK to acknowledge receipt:
â Only use error codes when absolutely necessary:
- 408 â Server too slow
- 429 â Too many requests
- 5xx â Server is down/broken (no retries will be attempted)
What Developers Should Expect
No setup changes are required for developers already using externally shared Marketplace webhooks.
With this enhancement:
- HTTP 429 retry behavior remains unchanged
- non-429 failures now retry automatically with exponential backoff
- retry attempts for non-429 failures may continue for up to 3 days
This gives developers a longer recovery window when webhook endpoints are temporarily unstable or unavailable.
Recommended HTTP Response Codes
Understanding when to acknowledge or throttle requests is critical:
- 200 OK â Always send for successful processing. If your downstream job queues the work asynchronously, still return 200 so SourCherry knows the event was received.
- 429 Too Many Requests â Return only when you genuinely need SourCherry to slow down; triggers the retry flow outlined above.
- 408 Request Timeout â Optional signal that your server could not process the call in time.
- 5xx Server Errors â Indicate a hard failure on your side; no further retries will be made.
Frequently Asked Questions
Q: Will SourCherry deduplicate events across retries?
Yes. Each webhook attempt uses the same deliveryId header so you can safely ignore duplicates.
Q: Can I customise the retry interval or number of attempts?
Not at this time. The 10-minute / 6-attempt schedule is global.
Q: Do retries respect my APIâs existing rate limits?
Yesâjitter plus the 10-minute delay minimizes bursts, but you should still budget for up to six additional calls per event.
Q: What happens if my endpoint returns 404 or 400?
SourCherry treats non-429 responses as final; no further retries occur.
Q: How do I test this in a staging environment?
Return a mock 429 response from your staging endpoint and confirm SourCherry re-sends the payload six times over ~70 minutes.
Q: Does this affect Workflow âInbound Webhookâ triggers?
No. Automated retries apply only to Marketplace app webhooks sent from SourCherry to your external server.
Q: Where can I see historical delivery logs?
The Webhook Dashboard (coming soon) will expose per-attempt logs; until then, rely on your own server logs.
Q: Is there a size limit for payloads?
YesâMarketplace webhooks are capped at 256 KB. Larger payloads are truncated with a payloadTooLarge flag.
Q: How do I opt-out?
Retry logic is built-in and cannot be disabled per app. Design your endpoint to handle idempotency.
Q: Will SourCherry ever retry 5xx errors?
Noâ5xx responses represent an internal server error; SourCherry stops immediately so you can investigate without extra load.