Retry & Deliverylink

Understand how Infraspeak handles webhook delivery, retries, and failure scenarios.

Delivery Guaranteeslink

Aspect	Guarantee
Delivery attempt	At least once
Order	Not guaranteed
Timing	Near real-time (seconds)
Duplicates	Possible (use idempotency)

Successful Deliverylink

A delivery is considered successful when your endpoint returns:

HTTP status code 2xx (200, 201, 202, etc.)
Within 30 seconds

Infraspeak → send webhook → Your Endpoint
                          ← 200 OK
✓ Delivery complete

Retry Behaviorlink

When delivery fails, Infraspeak retries with exponential backoff:

Attempt	Wait Time	Cumulative Time
0	Immediate	0
1	2 minutes	2 minutes
2	4 minutes	6 minutes
3	8 minutes	14 minutes
4	16 minutes	30 minutes
5	32 minutes	~1 hour
6	64 minutes	~2 hours
7	~2 hours	~4 hours
8	~4 hours	~8 hours
9	~8 hours	~17 hours
10	~17 hours	~34 hours
11	~34 hours	~68 hours
12	~68 hours	~5,5 days

Maximum retry period: ~5,5 days

After 12 failed attempts, the webhook is marked as failed and no further retries occur.

Retries for a particular webhook always goes with same value for the X-Request-Uuid HTTP request header, which you can use to prevent duplicate events.

Failure Conditionslink

Deliveries fail when:

Condition	Behavior
Connection timeout	Retry
Response timeout (>30s)	Retry
Non-2xx status code	Retry
SSL/TLS error	Retry
DNS resolution failure	Retry
Connection refused	Retry

Automatic Deactivationlink

Webhooks are automatically deactivated after consistent failures to ensure system reliability.

Deactivation triggers:

Slow receivers: the webhook experiences a timeout when attempting to connect to the webhook receiver or reaches the timeout limit while waiting for a response.
Unstable receivers: the webhook receiver returns a response code other than 2xx range (3xx, 4xx or 5xx).
Incorrectly configured receivers: the webhook encounters invalid HTTP responses.

When deactivated:

The webhook configuration status changes to INACTIVE.
No further deliveries are attempted.
All admins are notified by email. Disabled webhooks can be manually re-enabled.

Best Practiceslink

Respond quickly: return 2xx within 30 seconds. For heavy processing, process asynchronously. A common strategy is to store the request payload on a message queue, respond with a 200 OK, and use a background worker to process the messages in the queue.
Monitor webhook health to avoid webhook auto-deactivation.
Use the request header X-Request-Uuid to handle duplicate deliveries (idempotency).
Handle Out-of-Order delivery since events may arrive out of order. A common strategy is to compare the payload's update date (e.g.: updated_at, date_updated) with your existing's update date: if you have a newer state, ignore the older event.