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
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