Hooks and filters

OctaForms exposes a set of filters and actions in the octa_forms_ namespace. This page is a reference. Two of the most useful, custom validation rules and theme sync, have their own pages.

Actions

Action	Fires	Arguments
`octa_forms_submission_created`	After a submission is stored, before delivery. The place to push data into your own systems.	`$submission`, `$form`
`octa_forms_loaded`	After the plugin has loaded and registered its hooks. The place for a companion plugin to attach, independent of load order.	`$version`
`octa_forms_developer_page`	When the developer page renders, so a tool can add its own section.	—
`octa_forms_callback_settings_footer`	At the bottom of the callback widget settings.	—

Example: react to every new submission.

add_action( 'octa_forms_submission_created', function ( $submission, $form ) {
    // Push $submission into your CRM, log it, etc.
}, 10, 2 );

Front-end assets

Filter	Controls
`octa_forms_frontend_assets_enabled`	Master switch for the whole JS/CSS bundle
`octa_forms_styles_enabled`	The stylesheet only
`octa_forms_helper_autobind`	The helper’s automatic form scan
`octa_forms_cron_nudge_enabled`	The browser cron nudge

See Frontend assets.

Validation and rules

Filter	Controls
`octa_forms_validation_rules`	Register your own rules. See Custom validation rules

Files and uploads

Filter	Controls
`octa_forms_max_file_bytes`	The hard per-file size cap
`octa_forms_allowed_file_types`	The extension whitelist for uploads
`octa_forms_is_uploaded_file`	Whether a temporary path counts as a real upload. Only override this to sideload a file you put on disk yourself
`octa_forms_max_mail_attachment_bytes`	The cap on files attached to notification emails
`octa_forms_upload_dir`	Where uploaded files are stored

Security, tokens and rate limiting

Filter	Controls
`octa_forms_client_ip`	How the visitor’s IP is determined (proxy setups)
`octa_forms_token_ttl`	How long a token is valid
`octa_forms_token_min_age`	The time-trap minimum age before a token is accepted
`octa_forms_token_throttle`	The per-IP throttle on the token endpoint
`octa_forms_rate_limit_defaults`	The rate-limit thresholds
`octa_forms_allow_unsafe_webhook_url`	Escape hatch for the webhook URL safety check

Anti-spam

Filter	Controls
`octa_forms_spam_check`	The content spam verdict, after validation and the file store, before the atomic save
`octa_forms_challenge`	The challenge gate, right after the honeypot. See Anti-spam
`octa_forms_akismet_enabled`	Whether the built-in Akismet adapter runs
`octa_forms_akismet_request`	The request body sent to Akismet

The content filter decides whether a stored lead goes to the spam quarantine. It receives the current verdict, the validated values and the form, and returns ham (keep) or spam (quarantine):

add_filter( 'octa_forms_spam_check', function ( string $verdict, array $values, $form ) {
  // Inspect $values, return 'spam' to quarantine or 'ham' to keep.
  return $verdict;
}, 10, 3 );

The default is ham, so a filter that does nothing never loses a lead. The bundled Akismet adapter hooks here. Turn it off for a single request with octa_forms_akismet_enabled, or reshape what it sends with octa_forms_akismet_request:

add_filter( 'octa_forms_akismet_request', function ( array $body, array $values, $form ) {
  // Adjust the comment-check body before it is sent.
  return $body;
}, 10, 3 );

The octa_forms_challenge filter is the mount point for a captcha or another challenge. Return block to reject the request. It is covered in full on Anti-spam.

Delivery and queue

Filter	Controls
`octa_forms_disable_inline_send`	Turn off the inline first attempt
`octa_forms_inline_breaker_threshold`	When the inline circuit breaker trips
`octa_forms_inline_budget_seconds`	Time budget for the inline attempt
`octa_forms_delivery_max_attempts`	How many times a delivery is retried
`octa_forms_queue_batch_size`	How many deliveries drain per run
`octa_forms_queue_budget_seconds`	Time budget for one drain
`octa_forms_queue_interval`	The WP-Cron drain interval
`octa_forms_queue_health_access`	Who may read the queue health endpoint
`octa_forms_cron_nudge_delay`	The browser nudge’s client-side delay
`octa_forms_cron_nudge_backoff`	The server-side back-off hint returned to the browser nudge
`octa_forms_queue_tick_throttle`	The cap on real drains from browser nudges
`octa_forms_confirmation_throttle`	The per-recipient throttle on confirmation emails
`octa_forms_webhook_payload`	The webhook payload before it is signed and dispatched

Email

Filter	Controls
`octa_forms_allowed_sender_domains`	Which sender domains are considered safe
`octa_forms_email_layout_path`	The per-theme HTML email layout path
`octa_forms_mail_variables`	The `{field}` variables available in email subjects and bodies

Request limits

Filter	Controls
`octa_forms_max_body_bytes`	The maximum request body size
`octa_forms_max_field_chars`	The maximum length of a single field value

Privacy and retention

Filter	Controls
`octa_forms_anonymize_value`	How a value is anonymized on erase
`octa_forms_spam_retention_days`	How long the spam quarantine is kept

Visit path

Filter	Controls
`octa_forms_user_path_enabled`	Whether the visit path is collected at all
`octa_forms_user_path_limits`	The entry count, TTL and per-entry length caps
`octa_forms_user_path_require_consent`	Whether a CMP signal is required before anything is collected

See Visit path.

Filter	Controls
`octa_forms_callback_settings`	All widget settings, before normalization
`octa_forms_callback_phone`	The widget’s phone number (fallback)
`octa_forms_callback_config`	The final config sent to the browser
`octa_forms_callback_visible`	Whether the widget shows on a given page
`octa_forms_callback_slug` / `octa_forms_message_slug`	The backing forms’ slugs

See Callback widget.

Theme sync

Filter	Controls
`octa_forms_theme_form_dirs`	The directories scanned for theme form files
`octa_forms_theme_import_status`	The status of forms created by an import

See Forms in your theme (sync).

Export and import

Filter	Controls
`octa_forms_import_max_bytes`	The largest export file the importer accepts (2 MB by default)

See Export and import forms.

Response and setup

Filter	Controls
`octa_forms_response`	The success response body
`octa_forms_seed_starter_forms`	Whether the starter form is seeded
`octa_forms_enable_developer_menu`	Whether the developer menu appears
`octa_forms_enable_dev_reset`	Whether the dev content reset is available