Automated Webhook Retries for Sparkforge Marketplace Apps

By Sparkforge Support Team ·Last reviewed May 3, 2026

Sparkforge Marketplace retries outbound webhooks only on HTTP 429 responses, with randomized jitter on a 10-minute interval, up to six attempts. All other status codes — 2xx, 4xx, 5xx — are treated as final.

When your Marketplace app's endpoint returns HTTP 429 (Too Many Requests), Sparkforge re-sends the same payload up to six times on a spaced-out schedule with jitter. Every other status code stops retries immediately — predictable behavior that protects both your servers and event delivery.

Retry rules

Only retried status: 429.
Stop conditions: any non-429 response (200, 202, 204, 4xx, 5xx).
No 5xx retries: server errors are treated as permanent so we don't hammer a downed endpoint.

Retry schedule

Interval: 10 minutes between retries, with randomized jitter.
Max attempts: 6.
Total worst case: about 1 hour 10 minutes.

Jitter (a small randomized offset on each interval) prevents simultaneous retry bursts. If multiple events get throttled at once, their retries spread out instead of all firing in the same instant — which avoids cascading rate-limit hits.

Recommended response codes

200 OK — always send for successful receipt. If your downstream queues work asynchronously, still return 200 to acknowledge.
429 Too Many Requests — return only when you genuinely need Sparkforge to slow down. Triggers the retry flow.
408 Request Timeout — optional signal that you couldn't process in time.
5xx — hard failure on your side. Sparkforge stops; investigate the server.

How to use it as a developer

Return 200 OK on successful processing.
If you queue work asynchronously, still return 200 OK. The event was received.
Reserve error codes for genuine signals: 408 for timeout, 429 for rate-limit, 5xx for server failure.
Design endpoints for idempotency. Use the deliveryId header to deduplicate.

Limits to know

Marketplace webhook payloads are capped at 256 KB. Larger payloads are truncated with a payloadTooLarge flag.
The retry schedule is global — interval and attempt count are not configurable.
Retries cannot be disabled per app; design for idempotency instead.

FAQ

Will Sparkforge deduplicate events across retries?

Yes. Each attempt carries the same deliveryId header so you can safely ignore duplicates.

Can I customize the retry interval or attempt count?

No. The 10-minute, six-attempt schedule is global.

Do retries respect my API's existing rate limits?

The 10-minute spacing plus jitter minimizes bursts, but plan for up to six additional calls per event.

How do I test retries in staging?

Return a mock 429 response from your staging endpoint and confirm Sparkforge re-sends the payload six times over roughly 70 minutes.

Frequently Asked Questions

Will Sparkforge deduplicate webhook events across retries?

Yes. Each retry uses the same deliveryId header. Use that header on your end to detect and ignore duplicate deliveries safely.

Can I customize the retry interval or maximum attempts?

No. The 10-minute interval and six-attempt cap are global and cannot be configured per app. Design your endpoint for idempotency instead.

Does Sparkforge retry on 5xx server errors?

No. 5xx responses are treated as permanent failures so a downed endpoint isn't hammered. Only HTTP 429 responses trigger retries.

What happens if my endpoint returns 404 or 400?

Sparkforge treats any non-429 response as final. No further retries occur — the event is considered delivered (or rejected) on that response.

Is there a payload size limit for Marketplace webhooks?

Yes. Marketplace webhook payloads are capped at 256 KB. Larger payloads are truncated and flagged with a payloadTooLarge indicator.