Each message Illizeo sends to a webhook is a delivery, tracked from the first attempt to the final result. This article explains how to read a webhook’s page, what the statuses mean, how automatic retries and deactivation after failures work, and how to retry a delivery by hand. It is for the administrators who monitor integrations.
Before you start #
- The “Webhooks — View” permission is enough to read a webhook’s page and its deliveries, under Settings › Manage Illizeo › Webhooks.
- Retrying a delivery, sending a test or reactivating a webhook require the “Webhooks — Create / edit / delete” permission at the Execute level (see Creating and managing a webhook).
A webhook’s page #
In the list, click a webhook’s name or the View icon. The header shows its state (Active or Inactive), its Receiving address, the beginning of its Signing secret, its Events, its creation date and creator, and, if it is failing, the date of the first failure under Failing since. The Send a test, Rotate secret and Edit buttons are reserved for the Execute level.
Four counters sum up the last 30 days, tests excluded: Delivered (30 d), Retrying, Failed (30 d) and Pending.
The deliveries table #
The Deliveries table lists the messages sent, newest first, twenty per page, with a status filter (All statuses by default):
- Date and Event (its code, for example
absence.approved, orpingfor a test); - Status and Attempts (the number of tries already made);
- Response: the HTTP code returned by the receiver and the response time, with the reason for a failure in red;
- Next retry: the date of the next try, if there is one.
At the end of the row, Show payload expands the JSON message sent, and Retry now appears for a delivery that is retrying or failed.
Statuses #
| Status | Meaning |
|---|---|
| Pending | The delivery is in the sending queue; it goes out within seconds. |
| Delivered | The receiver answered with a 2xx code. |
| Retrying | The last attempt failed; another one is scheduled at the date in the Next retry column. |
| Failed | Every attempt failed, or the delivery was stopped (see the reasons below); no more automatic retries. |
Automatic retries #
An attempt fails when the receiver does not answer with a 2xx code within 10 seconds; a redirect also counts as a failure. Illizeo then retries the delivery 1 minute, 5 minutes, 30 minutes, 2 hours and then 12 hours after the previous failure: six attempts in all. After the sixth, the delivery becomes Failed.
All attempts of the same delivery carry the same event identifier, which lets the receiver discard a duplicate.
Retrying by hand #
Retry now makes an immediate attempt. The result is shown straight away: “Delivered”, or “Still failing” with the reason. A manual retry is never followed by automatic retries: if it fails on a delivery that was retrying, the remaining scheduled tries are dropped and the delivery becomes Failed. It remains possible when the webhook is deactivated: this is how to resend a missed delivery once the receiver is fixed.
Deactivation after failures #
When a webhook fails continuously for three days, with no successful delivery in between, Illizeo deactivates it:
- the list shows Disabled after failures and the webhook page a red banner;
- its creator receives a notification in the bell and by email, if they still have the permissions to view and manage webhooks;
- no more events are sent to it, and those that occur while it is deactivated are not kept aside.
To start again: fix the receiver, click Send a test to check it, then reactivate the webhook with the switch in the list. Retry the failed deliveries that matter if needed.
Reasons for a failure #
| Reason shown | Meaning |
|---|---|
http_ followed by a code (for example http_500) |
The receiver answered, but with an error or a redirect. |
| A connection message (timeout, name not found…) | The receiver did not answer within 10 seconds, or cannot be reached. |
abonnement_desactive |
The webhook was deactivated before the next attempt. |
destination_refusee followed by a reason |
The address is no longer accepted (it leads to an internal network or is no longer https). |
plafond_de_consommation |
The usage safety cap has been reached: deliveries stop until the next period. |
Good to know #
- Every night, delivered or failed deliveries older than 30 days are deleted. Deleting a webhook also deletes its whole log.
- Each successful delivery counts as one unit of API platform usage; tests and retries do not count extra. Usage is shown on the API platform card of the token page (see Monitoring and troubleshooting an API token).
- A successful test does not reset a series of failures: only a real successful delivery, or reactivation, does.
FAQ #
The receiver says it got the message, but the delivery is “Retrying”. #
It probably answered too late (more than 10 seconds) or with a code other than 2xx. It should answer at once and process the message afterwards.
The Last delivery column of the list says “Never” although I sent a test. #
Tests are not taken into account there, nor in the counters. They only appear in the deliveries table.
