How delivery works

This is the part of OctaForms that makes it different from a typical contact form plugin, so it is worth understanding even if you never touch a line of code.

The promise: durability before timeliness

When a visitor submits a form, OctaForms writes the submission and everything it needs to deliver into a durable queue in the database before it returns the success response. Only then does the visitor see “thank you”.

The consequence is simple: once a visitor gets a success, the submission is safe. It does not depend on your mail server being reachable at that exact second, or on a webhook endpoint being up. If any of that is down, the data is already stored and delivery will be retried.

The trade is deliberate. Under load or during an outage, a notification might reach your inbox a minute late. It is never lost.

What happens on submit

1. The submission passes through the intake checks (rate limiting, spam checks, validation) and is stored.
2. Every delivery it needs, the notification email, the confirmation email, each webhook, is written to the delivery queue.
3. The notification email gets one immediate attempt, inside the request, so in the normal case it arrives right away. This inline attempt is guarded by a circuit breaker: if your mail transport is failing repeatedly, OctaForms stops hammering it inline and lets the background job handle it instead.
4. The visitor gets their success response.
5. Anything not delivered inline, every webhook and any email that did not go through, is picked up by a background job.

Retries and back-off

The background job drains the queue and retries failed deliveries with growing delays (exponential back-off), so a briefly unavailable endpoint is retried a few times rather than given up on or hammered.

The background job runs on WordPress cron. That has one important caveat: WP-Cron only fires when someone visits the site, and some hosting setups starve it. For timely delivery you should run a real system cron. This matters enough that it has its own page. See Cron and the delivery queue.

Nothing fails silently

The other half of the promise is visibility. Every protection and every degraded state leaves a trace you can find:

• The queue view in the admin shows the backlog and any deliveries stuck retrying.
• Site Health carries a dedicated OctaForms check that goes red when the queue worker has not run for 15 minutes or more, when the inline circuit breaker is open, or when the token endpoint is unreachable.

So if delivery is falling behind, you find out from the admin, not from a customer asking why nobody replied.

Webhooks are at-least-once

Because delivery is retried, a webhook can in rare cases be delivered more than once. Receivers must handle that by deduplicating on the payload’s id. See Webhooks.