Adaptive AI Knowledge Base
Integrations & Mobile
This is the Webhook Integration Guide.
What is Marketplace Automated Webhook Retries?
Adaptive AI’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), Adaptive AI 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.
- Randomized retry timing prevents the “thundering herd” problem and spreads load evenly across servers.
Key Benefits of Marketplace Automated Webhook Retries
- – a fixed 10-minute interval (plus jitter) and six-attempt cap lets you model worst-case latency (~1 hr 10 min).
- – jitter prevents a “thundering herd” of simultaneous retries, spreading load evenly across your infrastructure.
- – 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.
- 10 minutes between retries (with jitter)
- 6 retries
- ~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.
- 429 only.
- 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.
- continue using the existing retry behavior with a fixed 10-minute interval for approximately 1 hour.
- now also retry, including temporary endpoint downtime, server errors, timeouts, and transient network issues.
Jitter Protection
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:
- – Always send for successful processing. If your downstream job queues the work asynchronously, still return 200 so Adaptive AI knows the event was received.
- – Return only when you genuinely need Adaptive AI to slow down; triggers the retry flow outlined above.
- – Optional signal that your server could not process the call in time.
- – Indicate a hard failure on your side; no further retries will be made.
Frequently Asked Questions
Q: Will Adaptive AI 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.
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?
Adaptive AI 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 Adaptive AI 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 Adaptive AI 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 Adaptive AI ever retry 5xx errors?
No—5xx responses represent an internal server error; Adaptive AI stops immediately so you can investigate without extra load.