Handle webhook retries and failures

Treat a webhook as a prompt to re-read, not as a ledger. Most changes produce a delivery within seconds, but a few never do, and some arrive twice. This page covers what happens when delivery fails, and how to build a receiver that is correct anyway.

How failed deliveries are retried

A delivery that does not get a 2xx within 10 seconds is retried 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours after the first attempt: six attempts over about eight hours. A delivery that has not succeeded after 24 hours is abandoned.

When an endpoint is disabled

After five failed deliveries in a row, Hermes disables the endpoint and emails its owner. Fix your receiver, then re-enable the endpoint on the Notifications tab. Re-enabling also resets the failure count.

Handle duplicates

The same change can reach you more than once, for example when your receiver processed an attempt but timed out before responding. Deduplicate on the delivery id, which stays the same across retries, and make your handler safe to run twice.

Reconcile on a schedule

A few changes produce no delivery at all, so a receiver that relies only on webhooks will eventually miss one.

• A change made while Hermes is restarting, for example during a deploy, may not produce a delivery. Nothing is retried, because nothing was sent.
• A search or retrieval run that fails does not clear its request flag. The flag stays true and the run is retried quietly, so no completion event arrives until a later attempt succeeds. A patient can therefore sit with a flag set for much longer than one run normally takes.

Re-read the records you care about periodically, for example once a day, and treat webhooks as the fast path on top.

Debug a receiver

Notifications → Endpoint Logs lists every delivery attempt: its status (pending, succeeded, failed or abandoned), the attempt count, and the last HTTP status your receiver returned.

Next steps

• Receive webhook events: create an endpoint and verify deliveries.
• Manage webhook endpoints: rotate the signing secret without missing a delivery.