Cron and the delivery queue

Deliveries that are not sent inline, every webhook and any retried email, wait in a queue that a background job drains. This page explains how that job runs, and how to make sure it actually does.

Why WP-Cron is not enough

WordPress’s built-in cron is not a real scheduler. It only fires when someone visits the site. On a quiet site, or one where a page cache serves visitors without booting PHP, it can go long stretches without running. And the mechanism WordPress uses to trigger it relies on a loopback request that many hosts block.

The result is that deliveries can pile up and arrive late. Remember that this is only about timeliness. Nothing is lost, because every delivery is stored before the visitor’s success response. But late is still bad for a lead.

The fix: a real system cron

Run OctaForms’ drain command from a real system cron every minute:

wp octa-forms queue drain

This runs the queue worker directly and does not depend on WP-Cron or a loopback at all. It is the recommended production setup. A typical crontab line:

* * * * * cd /path/to/wordpress && wp octa-forms queue drain >/dev/null 2>&1

Alternatively, set DISABLE_WP_CRON and run wp cron event run --due-now from your system cron.

The browser nudge (a fallback, not a replacement)

For sites that cannot set up a system cron, OctaForms includes a best-effort fallback: browser traffic gently nudges the queue to drain.

• After a successful submit, the visitor’s browser pings the queue so a fresh webhook drains immediately, from the browser that just reached your server, sidestepping a blocked loopback.
• On other pages, a small idle-time ping keeps the queue moving.

This is careful, not chatty. A server-side limit caps real drains to about once a minute no matter how many pings arrive, and the plugin detects whether your cron is actually healthy and stays quiet when it is. The whole thing is cache-immune: the decision to nudge is never baked into a cached page.

The nudge is genuinely best-effort. On a site with no traffic at all, retries still need a real cron. So a system cron stays the recommendation; the nudge just softens the failure mode for everyone else.

To turn the nudge off, use the disable_cron_nudge setting or the octa_forms_cron_nudge_enabled filter. Tuning filters are listed in Hooks and filters.

Checking it is working

Site Health carries an OctaForms delivery-queue test. It goes red when the worker has not run for 15 minutes or more. The admin queue view shows the current backlog and anything stuck retrying. If either looks wrong, your cron is the first thing to check.