Delivery Configuration and Reliability
Configure and document webhook delivery guarantees, retry policies, dead letter queues, circuit breakers, rate limiting, and timeout handling. Covers at-most-once, at-least-once, and exactly-once delivery semantics with architectural guidance for production reliability.
Webhook delivery reliability is the difference between an integration that works in testing and one that works in production. Consumers need to understand the provider's delivery guarantees, retry behaviour, timeout thresholds, and failure handling strategies to build resilient integrations. NeoArc Studio captures all delivery configuration in the root webhook API definition so that consuming teams have a complete picture of the reliability contract.
Delivery Guarantees
The delivery guarantee defines the fundamental reliability contract between the webhook provider and consumer. Three delivery semantics are available, each with different implications for consumer implementation.
Response Timeout
The response timeout defines how long the provider waits for the consumer to respond before marking a delivery as failed and queuing it for retry.
Retry Policy
The retry policy defines how the provider handles failed deliveries. Document the full retry schedule so consumers can size their monitoring windows and understand the total delivery attempt timeline.
Example Retry Schedule
A typical production retry schedule with exponential backoff:
| Attempt | Delay After Previous | Cumulative Time |
|---|---|---|
| 1 (initial) | Immediate | 0 seconds |
| 2 (retry 1) | 1 minute | 1 minute |
| 3 (retry 2) | 5 minutes | 6 minutes |
| 4 (retry 3) | 15 minutes | 21 minutes |
| 5 (retry 4) | 1 hour | 1 hour 21 minutes |
| 6 (retry 5) | 4 hours | 5 hours 21 minutes |
Dead Letter Queue
The dead letter queue (DLQ) stores events that have exhausted all retry attempts. Document whether your platform provides a DLQ and how consumers can access and replay failed events.
Circuit Breaker
The circuit breaker protects both the provider's delivery infrastructure and the consumer's failing endpoint by temporarily suspending delivery after a configurable number of consecutive failures.
Rate Limiting
Rate limiting controls the maximum delivery rate to prevent overwhelming consumer endpoints during high-volume event periods.
| Aspect | Description |
|---|---|
| Per-Endpoint Rate | Maximum deliveries per second to a single consumer endpoint. Document whether this is configurable by the consumer. |
| Burst Allowance | Whether short bursts above the rate limit are permitted. Document the burst window and maximum burst size. |
| Backpressure Behaviour | What happens when the rate limit is reached: queueing with delay, dropping with DLQ routing, or returning rate-limit headers for consumer-side throttling. |
| Rate Limit Headers | Whether responses include rate-limit headers (X-RateLimit-Remaining, Retry-After) that consumers can use for adaptive behaviour. |
| Global vs Per-Endpoint | Whether the rate limit applies globally across all endpoints or independently per consumer endpoint. |
Ordering Guarantees
Event ordering is a frequently misunderstood aspect of webhook delivery. Document the ordering guarantees explicitly to prevent consumers from making incorrect assumptions.
Configuring Delivery in NeoArc
The webhook API editor provides dedicated sections for all delivery configuration. Here is how each setting maps to the editor interface.