Delivery and retries
What counts as a successful delivery, how long BreezeAuth waits for your endpoint and how failed deliveries are retried.
This page explains what happens between the moment an event occurs in your organization and the moment your endpoint acknowledges it, including what BreezeAuth does when something goes wrong.
Delivery
When an event occurs, BreezeAuth sends it, usually within a few seconds, to every enabled webhook of the
organization that subscribes to that event type. Each delivery is an HTTP POST request to the webhook URL, with the
message in the body as JSON and the signature headers.
What counts as success
An attempt is successful only when your endpoint responds with a 2xx status code (200 to 299) within
15 seconds. Anything else is a failure:
| What your endpoint does | Result |
|---|---|
Responds 2xx within 15 seconds |
✅ Success. The response body is ignored. |
Responds with a redirect (301, 302, 307, 308…) |
❌ Failure. Redirects are not followed. Register the final URL instead. |
Responds 4xx (such as 400, 401, 404) |
❌ Failure. |
Responds 5xx (such as 500, 502, 503) |
❌ Failure. |
| Takes longer than 15 seconds to respond | ❌ Failure (timeout). Your endpoint may still have processed the message, so expect a duplicate. |
| Can’t be reached (DNS error, connection refused, invalid TLS certificate) | ❌ Failure. |
Important: 3xx responses are treated as errors. A common cause is registering http:// when the server redirects
to https://, or omitting a trailing slash the server insists on. Use the exact final URL.
Retries
When an attempt fails, BreezeAuth tries again. Each event gets up to 3 attempts per webhook: the original delivery plus 2 retries.
| Attempt | When it happens |
|---|---|
| 1 | Right after the event occurs. |
| 2 | About 5 seconds after attempt 1 failed. |
| 3 | About 30 seconds after attempt 2 failed. |
If the third attempt also fails, BreezeAuth gives up on that event for that webhook. Counting the 15-second timeout of each attempt, all attempts happen within about a minute and a half of the event.
All attempts carry exactly the same message: the same webhook-id, webhook-timestamp and body. That is what lets
your endpoint recognize duplicates.
Note: the retry window is short on purpose. Webhooks are meant to notify you of changes quickly, not to queue messages for an endpoint that is down. If your endpoint may be unavailable for longer, add a periodic reconciliation through the API.
Configuration changes during retries
Before each attempt, BreezeAuth reads the webhook’s current configuration:
- if the webhook was disabled, or the event type was removed from its subscriptions, the remaining attempts are cancelled;
- if the URL was changed, the next attempt goes to the new URL.
Delivery guarantees
- At least once. BreezeAuth makes every effort to deliver each event, and in some situations may deliver the same event more than once. Your endpoint must ignore duplicates.
- No ordering guarantee. Events are delivered independently and retries add delays, so messages can arrive in a different order than the events happened. Read the current state from the API instead of relying on order.
- One message per event. Each message describes exactly one event; there is no batching.
When deliveries fail
Every attempt, successful or not, is recorded in the webhook’s Event History, with the status code or error that caused the failure. See Event history to investigate problems.
Last updated: October 13, 2026