Inbox polling vs webhooks: choose by failure behavior.

Start with the lifetime of the caller

A Playwright test has a live process, a known trigger, and a deadline. It can wait for one matching message and stop. Adding a public webhook endpoint, queue, correlation store, and cleanup job may create more failure modes than it removes. A bounded wait operation or polling loop is usually the smaller design.

A support agent service or workflow engine may run for months and receive messages when no initiating process is alive. Polling every mailbox from every worker wastes requests and complicates concurrency. A verified webhook that writes to a durable queue is a better notification mechanism, as long as the mailbox or event store remains available for recovery.

The choice should follow process lifetime and workload shape, not a blanket claim that webhooks are modern or polling is simple. Both require explicit state.

Poll with a cursor, exact filters, backoff, and a deadline

Record the trigger time before the external action. Query the intended mailbox and direction for messages received afterward, with sender or subject context where reliable. Keep the page size small. If there is no match, back off with jitter and continue until the deadline. If there are several valid candidates, return ambiguity instead of choosing the newest globally.

A dedicated wait-for-code operation can package these rules and return a narrow result. The caller should still assert that the code or link changed the outside application state. Receipt and extraction are intermediate evidence.

Persist a cursor or last processed message ID when polling a long-lived mailbox. Without one, a restart can reprocess old mail or require repeatedly scanning the whole history. Use provider timestamps carefully because delivery order and original sent time can differ.

• Cap attempts and total elapsed time.
• Honor rate-limit responses and server retry guidance.
• Add jitter so parallel jobs do not synchronize requests.
• Report no message, ambiguous match, parse failure, and timeout separately.

Acknowledge quickly and move work into a durable consumer

The public endpoint should verify the signature or provider authentication, validate basic envelope shape, store or enqueue the event, and respond quickly. It should not run a long model call, download every attachment, or perform a fragile external action before acknowledgement. Slow handlers increase retries and duplicate work.

Use a stable event or message identifier as the idempotency key. The first consumer transition can claim the event; later deliveries should observe the recorded state and stop. If the provider does not supply a reliable identifier, derive a bounded fingerprint from mailbox, message headers, and payload metadata while retaining the original event for diagnosis.

A valid webhook proves that the event came through the expected transport path. It does not make the email body, links, or requested action trustworthy. Apply workflow eligibility and content policy after transport verification.

Use notification for speed and mailbox state for truth

Webhooks can fail because DNS, certificates, signatures, deploys, queues, or handlers fail. Polling can fail because a process ends, a filter is wrong, or rate limits intervene. A hybrid design treats the webhook as a prompt to inspect durable mailbox state, not as the only copy of the message.

Store the last reconciled cursor per mailbox or workflow. On startup and on a schedule, query messages after that cursor and enqueue anything not already processed. The same idempotent consumer handles webhook and reconciliation events. This prevents two separate business paths from drifting.

Measure latency and loss at each boundary

Record message ingestion time, notification attempt, endpoint acknowledgement, queue availability, consumer start, business transition, and final application outcome. A single end-to-end latency number cannot tell the team whether transport, notification, queueing, model work, or the external system caused the delay.

Alert on a rising webhook retry rate, reconciliation gaps, old unprocessed messages, repeated ambiguity, and polling rate limits. Keep bodies, OTPs, addresses, and secrets out of broad telemetry. Use message and workflow identifiers that operators can resolve through restricted tools when investigation is necessary.

Sources and product scope

Product behavior is verified against the mails0 source and documentation. External comparisons link to official vendor documentation checked on 2026-08-15.

Related implementation paths