InnerWeb
Skip to main content

n8n poller and retries: implementation notes

Switching on the poller is the moment when webhooks really start leaving the plant, so configuration mistakes cost alarms. Before the start, the IT administrator should check four things: the account, the acknowledgements, the retries and their limits. Below is the order of work and the pitfalls worth knowing in advance.

89
entries in one batch
Source: karta
300 s
reservation limit before the entry returns to the pool
Source: karta

Prerequisites before the start

The poller works in outbox mode, so the first prerequisite is switching the webhook delivery mode setting. Any value other than outbox means direct, so after the change run a test event and confirm that the entry appeared in the table and was not sent directly.

The second prerequisite is a technical account for the poller with a scope limited to fetching entries and confirming deliveries. The third is a network segment from which the poller can reach the application over an inbound channel and the final recipient. The fourth is an appointed owner of the workflow on the IT side.

How the fetch and acknowledgement cycle works

The poller fetches pending entries, and the system atomically reserves a batch of up to 89 entries under a write lock in a transaction. This way two pollers do not take the same entry, and an alarm does not ring twice. After sending, the poller acknowledges each entry as delivered or failed, with an optional error description.

The acknowledgement is idempotent: repeating an acknowledgement of an entry that is already delivered changes nothing. This matters during network failures, because the poller can safely repeat an acknowledgement when it got no response.

When an entry returns to the pool

An entry in the delivering state whose reservation lasts longer than 300 seconds returns to the pool and can be fetched again. In practice this means a single batch should not take longer than a few minutes, and the workflow should have its own time limit shorter than 300 seconds. Otherwise the same batch will be processed a second time while the first one is still running.

Limits of the poller mechanism

Limits of the poller mechanismBar chart: 89 entries in a batch, a 300-second reservation, an attempt limit of zero, meaning no limit.0100200300valueEntries in a batch: 89 value89 valueEntries in a batchReservation (s): 300 value300 valueReservation (s)Attempt limit (none = 0): 0 value0 valueAttempt limit (none = 0)
Source: Description of the Webhook Outbox feature (product documentation); zero means the system has no attempt limit

Retries and their limits

A failed acknowledgement, failed, returns the entry to the pending state and increases the attempt counter. The poller therefore retries the entry without end. This behaviour is an advantage for alarms that must not be lost, but it has limits that you need to know before switching on.

The system has no retry limit, no delay between retries and no alert for stuck entries. An entry that the recipient rejects permanently, for example because of a wrong address, will be fetched and returned over and over, loading the poller and cluttering the log. The missing mechanisms have to be replaced with a procedure on the workflow side: its own attempt counter in n8n, a delay between attempts and an alert when an entry is repeated too many times.

Order in the table and supervision

No task cleans up the table, so finished entries grow without end. The administrator should define a retention policy: how long to keep finished entries and who deletes them. Without this, the table in an installation with heavy traffic will become a performance problem after a few months.

Three indicators are enough for supervision: the number of pending entries, the age of the oldest pending entry and the number of attempts of the most retried entry. The alarm should be triggered by the age of the oldest pending entry, because it shows that the poller has stopped or the recipient is not responding.

Start-up order and acceptance

The recommended order: first a test environment with a fictitious recipient, then a test event with a confirmed delivered status, then a negative test with a recipient that rejects the event (to check how the attempt counter behaves), and finally the switch to the production recipient.

Acceptance ends with a protocol: the mode set, the account and its scope, the workflow time limit, the supervision indicators, the retention policy and the owner. Each of these points has evidence in the form of a configuration screenshot or a log entry.

Checklist

Video

Frequently asked questions

How many times will the poller retry a failed entry?

Without end. The system has no attempt limit and no delay between retries, so the limits have to be set in the workflow itself.

Can two pollers run in parallel?

Yes. Reserving a batch is atomic, so two pollers do not take the same entry.

Who cleans up the table of finished entries?

No system task does. The administrator has to set a retention policy and remove finished entries periodically.

A poller under supervision

We will prepare with your IT department a poller start-up plan: limits, supervision and an acceptance protocol.

Let's talk