Webhook delivery retry schedule

Webhook receivers and delivery workers need an explicit list of wait times before each retry, not a vague promise that backoff will be applied somewhere in the stack. This webhook delivery retry schedule builder takes a maximum retry count, a strictly positive base delay, and a strategy of fixed, linear, or exponential, then returns the per-attempt delays, cumulative waits, and a short formula string you can pin in tests or show next to a dashboard. The same pure logic runs free in the browser and over the API, so planning a five-retry exponential ladder offline matches what your edge worker will use when configuring notify paths or custom delivery loops. Invalid base delays fail fast with invalid_input instead of inventing zero or negative waits that would busy-loop a queue.

What a webhook retry schedule is and how the three strategies differ

Without a published schedule, operators cannot reason about worst-case delivery latency, and load tests cannot reproduce the exact gaps a production worker will insert between retries. Fixed backoff keeps the same base delay on every attempt: simple to reason about and kind to downstreams that only need a short cooling-off period. Linear backoff multiplies the base delay by the one-based attempt index, so later retries wait proportionally longer without exploding as fast as pure exponential growth. A webhook delivery retry schedule is the ordered list of delays you wait before attempt one, attempt two, and so on after a failed POST to a subscriber URL. This capability encodes three common backoff families used across message buses and HTTP clients. Exponential backoff doubles the previous delay each time using base_delay times two to the power of attempt minus one, which is the classic pattern for transient network faults and rate limits. You supply max_retries as how many retry slots to materialize, base_delay as the positive seed in your chosen unit (usually milliseconds), and strategy as one of fixed, linear, or exponential. The response echoes those inputs, lists delays in order, sums them as total_wait, and expands a schedule array with attempt number, delay, and cumulative wait so UI charts and config generators need no extra arithmetic.

Input contract, response shape, and when validation fails

POST a JSON body with three required fields. max_retries is an integer from one through one hundred naming how many retry attempts to schedule. base_delay is a finite number strictly greater than zero in any consistent unit; zero and negative values are rejected because a non-positive wait either busy-spins or is meaningless for scheduling. strategy must be the string fixed, linear, or exponential (case-insensitive after trim). Alias keys such as retries, base_ms, and backoff are accepted so existing config shapes map cleanly. Missing fields, non-integers for max_retries, non-finite base_delay, and unknown strategies all raise invalid_input and are not billed. On success the body includes max_retries, base_delay, strategy, delays as a flat array, total_wait as the sum of delays, attempt_count equal to max_retries, schedule as objects with attempt, delay, and cumulative fields, and formula restating the closed form for the chosen strategy. Example: max_retries five, base_delay one thousand, strategy exponential yields delays one thousand, two thousand, four thousand, eight thousand, and sixteen thousand with total_wait thirty-one thousand. Pair the schedule with your own jitter policy if you need random scatter; this endpoint intentionally omits jitter and wall-clock timestamps so results stay deterministic across browser and API paths. Cap max_retries at one hundred so a typo cannot expand into an enormous payload or overflow intermediate products for large exponential ladders.

Where building a retry schedule earns its keep in real systems

Load-test harnesses inject the same delay array the production worker uses, eliminating the classic gap where staging retries faster than production and masks rate-limit bugs. Delivery platforms that expose webhook reliability settings can call this builder when an operator picks max retries and a backoff mode, then store the resulting delays next to the endpoint secret and signing key. Incident runbooks benefit from a printable total_wait so on-call staff know how long a flaky subscriber may lag before the last attempt. OpenAPI and SDK generators can document concrete example ladders without hand-maintaining tables that drift from runtime code. Keep base_delay and total_wait in the same unit as your sleep primitives so you never convert milliseconds to seconds by accident when wiring the schedule into a worker loop.