Delivery, retries and logs
Kreezalid delivers webhooks at least once: a failed delivery is retried, and an event can reach you more than once. This page describes exactly what to expect, so your endpoint can be both fast and correct.
Timing
Section titled “Timing”A webhook is usually sent within seconds of the event. Under load or after an incident, it can be delayed by several minutes. Do not rely on webhooks for anything that must happen within a fixed number of seconds: use them to trigger work, and the Admin API to read the authoritative state.
Responding
Section titled “Responding”| Your endpoint answers… | Kreezalid records… |
|---|---|
a 2xx status |
a successful delivery. The response body is ignored, but kept in the logs. |
a 4xx or 5xx status |
a failed attempt, retried later. |
| nothing within 30 seconds | a failed attempt (timeout), retried later. |
| a connection or TLS error | a failed attempt, retried later. |
Answer as soon as the request is verified and stored, then process it in the background. A slow endpoint gets timeouts, and timeouts get retries: the same event then arrives several times.
Retries
Section titled “Retries”A failed attempt is retried with an increasing delay. The webhook is sent at most six times over about eight and a half hours:
| Attempt | Sent after the previous attempt |
|---|---|
| 1 | — (seconds after the event) |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
Every retry is a new request with a new X-Kreezalid-Timestamp and a new signature, the same
X-Kreezalid-Event-Id, and the object in its state at the time of the retry. After the
sixth failure the delivery is marked failed and is not retried any more. You can still
resend it by hand.
Automatic deactivation
Section titled “Automatic deactivation”A webhook whose deliveries keep failing is turned off: after 15 consecutive failed deliveries (each one after its six attempts), the webhook becomes Inactive and stops sending. One successful delivery resets the count.
An inactive webhook shows Inactive in Settings → Notifications → Webhooks, with its last error. To start again, fix your endpoint, delete the inactive webhook and create it again. The new webhook gets a new signing secret.
Deduplication
Section titled “Deduplication”The same event can arrive more than once: after a timeout, after a retry whose response was
lost, or after a manual resend. X-Kreezalid-Event-Id identifies the event and stays the same
across all of these. Store the identifiers you have processed, for at least a few days, and
skip the ones you have already seen.
The Send test notification button sends X-Kreezalid-Event-Id: test; do not store it.
Coalescing
Section titled “Coalescing”When the same object triggers the same event several times within about three seconds, for
instance a listing saved three times in a row by an import, Kreezalid sends one webhook
carrying the latest state, with the identifier of the latest event. The earlier events of
the burst are not sent separately. Design your processing around the state in data, not
around counting events.
Ordering
Section titled “Ordering”Webhooks are not guaranteed to arrive in the order the events happened: a retried delivery
can arrive after a later event, and different event types travel independently. To decide
whether a webhook is newer than what you hold, compare the created field of the envelope,
or read the object’s current state from the Admin API.
Logs and resend
Section titled “Logs and resend”Settings → Notifications → Webhooks → View logs lists the deliveries of the last 30 days, with their event, object, status and processing time. Open one to see the exact payload that was sent and the response your endpoint returned.
Resend sends a delivery again immediately, whatever its status, with the object in its
current state and the same X-Kreezalid-Event-Id. Use it to replay what your endpoint
missed during an outage, after you have fixed it.
Delivery logs are kept for 30 days. To rebuild anything older, use the Admin API.
Checklist
Section titled “Checklist”- Verify the signature and the timestamp of every request.
- Answer
2xxwithin a few seconds; process in the background. - Deduplicate on
X-Kreezalid-Event-Id. - Read the state from
data; do not assume events arrive in order or one by one. - Register the final URL; redirects are not followed.
- Run a periodic Admin API sync as a safety net, and watch the webhook logs.