Webhook retry and error handling

Overview

Webhook receivers are sometimes unreachable – a deployment, a timeout, an outage. Kyvento therefore doesn't lose any events, but retries failed deliveries at growing intervals over up to about nine days. This article explains the retry mechanics and how to build your receiver robustly.

What counts as a failure

A delivery is considered successful if your endpoint responds within 30 seconds with an HTTP status of 2xx. Everything else – 4xx, 5xx, timeouts, connection errors – counts as a failure and triggers retries.

The retry schedule

Kyvento makes a total of seven delivery attempts: the first immediately, then after approximately

1. 10 minutes
2. 1 hour
3. 6 hours
4. 24 hours
5. 72 hours (3 days)
6. 96 hours (4 days)

The final attempt therefore lands roughly eight days after the first. The intervals grow slowly on purpose: a brief glitch is over within minutes, while a longer outage still gets several days to recover. Only if the final attempt also fails is the delivery considered permanently failed – and only then does Kyvento notify you ("Webhook delivery exhausted"). So your receiver survives a short deployment without consequence; the events arrive later, only their order is then not guaranteed.

The same curve for email delivery

This slowly escalating retry logic applies not only to webhooks but to both delivery channels: email delivery – of invoices or dunning letters, for example – follows exactly the same curve. That way every temporary disruption, a brief outage or greylisting on your mail server, gets several days to resolve on its own. Only once all attempts are exhausted does Kyvento notify the account owner that a delivery ultimately could not be made.

What does not follow this curve

This curve concerns delivery only (webhook and email) – it deliberately does not apply to payments. A declined card payment won't be covered after days of retrying, so payments have their own, more suitable flows:

• Your own Kyvento billing: If the charge for your Kyvento subscription fails, a grace period with several reminders applies instead of this curve, before access is restricted. See the article "When a Kyvento payment fails".
• Your own customers' payments: Overdue customer invoices go through your dunning process – configurable per account – not through this delivery curve. See "Enabling automated dunning".

Automatic deactivation

If 10 deliveries in a row fail, Kyvento automatically deactivates the endpoint – a permanently dead receiver should not tie up resources. After the repair, you reactivate the endpoint in the webhook settings; events that occurred in the meantime are then not delivered retroactively. After longer outages, therefore check your data state via an API query.

Keeping error diagnosis in view

For each endpoint, the "Recent deliveries" section shows the most recent delivery attempts with status, HTTP response code and time. The complete history including response details is provided by the API (GET /v1/webhooks/{id}/deliveries) – useful when your receiver produces errors that you can't reproduce locally.

Building a robust receiver

1. Respond quickly, process asynchronously: Acknowledge receipt immediately with 2xx and process the event afterwards in your own queue – this way you never run into the 30-second timeout.
2. Process idempotently: Retries mean the same event can arrive multiple times. Deduplicate via the event ID (id in the payload) – not via the delivery ID, which is new for each attempt.
3. Verify the signature first (see "Configuring webhooks") – reject invalid requests with 4xx.
4. Don't assume an order: Due to retries, events can arrive in a changed order – rely on the object state (data.object) instead of on the sequence.

Good to know

• The retry timings can be adjusted per endpoint via the API, in case your system needs a different pattern.
• The connection test ("Send test") runs outside the retry system – it shows the immediate status but does not create a retry chain.

Next steps

• Set up endpoints and signatures – see "Configuring webhooks"
• Reload lost periods via the API – see "API documentation and examples"