From do_action to HTTP:
The Engineering Behind WordPress Webhook Delivery

The first challenge any webhook plugin faces: how do you show users a useful, accurate list of every hookable event on their specific WordPress install? The obvious answer is to read the global $wp_filter array — the data structure that add_action() and add_filter() write to, which contains every hook that has at least one registered callback at that moment.

This works for a small handcrafted list of common hooks, but it breaks down as soon as users want to use hooks from plugins like WooCommerce. The core issue is WordPress request context: when the admin UI calls GET /fswa/v1/triggers (a WP REST API request), WordPress bootstraps in REST mode. Many plugins register their hooks conditionally — only during front-end requests, only during admin-ajax.php, or only when a specific page template loads.

A hook like woocommerce_order_status_changed is registered by WooCommerce during the order processing lifecycle, which never runs during a REST API call. So $wp_filter during that request simply doesn't contain it. The same problem applies to hooks from form plugins, membership plugins, and anything that gates its add_action() calls behind is_admin(), !is_admin(), or specific action priorities.

The original workaround — a hardcoded getSuggestedTriggers() list of ~250 manually curated hooks — was immediately stale and said nothing about what was actually installed on the user's site.

Static scan: HookDiscoveryService

The solution is to combine what WordPress can tell us at request time with what the source code guarantees will fire at runtime. HookDiscoveryService.php does a one-time recursive scan of all active plugins (resolved to filesystem paths via WP_PLUGIN_DIR), WordPress core (wp-includes/ and wp-admin/), and the active theme and child theme.

For each PHP file it runs a single regex over the raw source:

This intentionally only matches string literal hook names. Dynamic hook names like do_action( "save_post_{$post->post_type}" ) are not captured — they cannot be statically known. The trade-off is conservative and noise-free; users can always type a custom hook name in the UI.

The regex was extended once in development (\/ was added to the character class) when IvyForms integration was added — its hooks follow a namespace/event/name convention like ivyforms/form/after_submission, and the original pattern didn't allow forward slashes. More on that in the integrations section.

RecursiveCallbackFilterIterator skips vendor/, node_modules/, and .git directories inside each plugin folder. The plugin's own files are excluded from the scan to avoid false positives.

Caching and cache invalidation

Scanning an entire WordPress install is not free. Results are stored in a WordPress transient (fswa_discovered_hooks_v3) with a 24-hour TTL. The cache is busted immediately on plugin activation, deactivation, and theme switches:

The cache key went through three versions (_v1, _v2, _v3) as the return format changed between releases. Bumping the key forces a clean rebuild on existing installs without a migration step — old transient values are simply ignored.

The scanner returns array<hookName, sourceSlug> — the hook name as key, the plugin directory name (e.g. contact-form-7) or wordpress for core as value. First plugin to define a hook wins on conflicts.

Neither $wp_filter nor the static scan alone is complete. The solution is to use both and merge them. TriggersController.php serves GET /fswa/v1/triggers and combines both sources into a single grouped response:

1. Iterate $wp_filter keys, apply an exclusion filter, and bucket each hook into a category.
2. Run HookDiscoveryService::discover() and merge any hook not already seen.
3. Return { grouped: { category: [hookName, …] }, categories: { key: label }, allowCustom: true }.

Exclusion filter

Hooks that are technically do_action calls but are useless as webhook triggers get dropped before reaching the UI. These are UI-only exclusions — they don't affect which hooks the plugin will intercept at runtime. A user can still type any hook name manually.

Category assignment

Runtime hooks from $wp_filter are bucketed by name-pattern matching — woocommerce catches anything starting with /^woocommerce/, users catches /user|login|logout|password|role|profile/, and so on.

Statically-scanned hooks from plugins are bucketed under their plugin slug. All Contact Form 7 hooks go under contact_form_7, displayed as "Contact Form 7". Third-party plugin hooks self-group with no hardcoded mapping required.

An earlier version of this API returned ~643 KB of per-hook metadata per request. The current version returns only names grouped by category; labels are computed client-side from the category key. On a site with WooCommerce and several form plugins active, the response now sits at 83.7 kB covering ~2,500 discovered do_action calls — a roughly 8× reduction with no loss of information for the UI.

Once a user saves a webhook with a trigger set to (say) wpcf7_before_send_mail, the plugin needs to listen on that exact action. HooksHandler.php does this at boot time by reading all configured trigger names and registering a listener for each:

PHP_INT_MAX as the accepted argument count means the handler receives every argument WordPress passes to the hook, regardless of arity. Without it, a hook that passes three arguments would only deliver the first one to the handler — the default for add_action is 1.

Deduplication

WordPress can fire the same hook multiple times in a single request — save_post fires on autosave, on the main save, and sometimes on meta updates. Delivering duplicate webhooks for the same event is a data quality problem for the receiver. Two deduplication layers guard against this:

In-process static lock — catches duplicate calls within the same PHP execution:

Cross-request transient lock (30 seconds) — catches the case where Action Scheduler or WP-Cron reschedules a job while the original request is still processing:

Every webhook delivery gets a consistent envelope, constructed in Dispatcher::dispatch():

$eventUuid is generated once per dispatch() call and shared across all webhooks subscribed to the same trigger. If five webhooks listen on woocommerce_order_status_changed, they all carry the same event.id. This lets the receiving end deduplicate or correlate deliveries without needing to match payloads. The UUID and timestamp are also sent as HTTP headers on every delivery: X-Event-Id and X-Event-Timestamp.

The serialization problem: normalizeArgs

WordPress hook arguments are untyped PHP values. They can be scalars, arrays, closures, objects, or any combination. normalizeArgs walks the argument list and applies type-specific handling:

Scalars — pass through directly as JSON-serializable values.
Arrays — recursed with the same normalization applied to each value.
Closure — not serializable; replaced with null.
DateTimeInterface — serialized to ISO 8601 atom string.
Traversable — iterated to a plain array.
JsonSerializable — jsonSerialize() is called.
Objects with get_data() — WooCommerce WC_Order, WC_Product, etc. follow this convention.
Objects with get_properties() — some WP core objects.
Everything else — get_object_vars() as a last resort.

Every serialized object gets a __type key set to get_class($value):

Without __type, two different object classes with identical field names would be indistinguishable on the receiving end. It also serves as documentation: the receiver knows exactly which WooCommerce or WordPress class produced each argument in the payload.

A filter escape hatch lets third-party code override normalization for specific classes before the default handling runs:

Generic reflection is fine for simple objects but produces unusable noise for complex CMS entities. The plugin ships built-in integrations for plugins whose hook arguments would otherwise be unreadable.

Contact Form 7

CF7 fires three hooks around mail sending: wpcf7_before_send_mail, wpcf7_mail_sent, and wpcf7_mail_failed. The problem is their $args signatures are not consistent — wpcf7_mail_sent and wpcf7_mail_failed only pass a WPCF7_ContactForm object. There is no submission data anywhere in $args. Without an integration, the webhook payload would contain form metadata but none of the fields the user actually submitted.

The fix relies on the fact that WPCF7_Submission is a singleton — it stays alive in memory for the duration of the request. Even when the hook only passes the form object, WPCF7_Submission::get_instance() returns the active submission. The integration verifies the singleton's form ID matches before pulling it in, so it never attaches a stale submission from a different form:

The $includeSubmission = false flag prevents recursion: when normalizeSubmission calls back into normalizeContactForm to embed the form reference, that inner call skips the singleton lookup. Internal CF7 fields (keys starting with _) are stripped from posted data before they reach the payload — so fields like _wpcf7, _wpcf7_version, and _wpcf7_unit_tag never appear in the webhook.

The final payload shape for a wpcf7_mail_sent event contains { id, title, name, locale, submission: { fields: {...}, meta: { url, timestamp, remote_ip, … }, uploaded_files: […] } } — the same shape regardless of whether the hook passed the submission directly or whether it was retrieved from the singleton.

IvyForms

IvyForms submission hooks (ivyforms/form/before_submission, ivyforms/form/after_submission) pass four arguments: (int $formId, array $submissionData, Field[] $formFields, int|null $entryId). The problem is that $submissionData is keyed by numeric field ID, while $formFields is an array of typed Field entity objects. A receiver getting the raw payload would need to cross-reference two separate arrays — matching numeric IDs to labels — to understand what was submitted.

The integration registers two filters. First, fswa_normalize_object converts each Field entity in args[2] to { id, label, type, required }. Then fswa_payload runs after normalization and injects the submitted value from args[1] into each already-normalised field entry:

The double lookup — (string) $fieldId first, then $fieldId as-is — handles the fact that PHP array keys may be stored as integers or strings depending on how IvyForms built the submission array. The result: args[2] in the final payload is a single self-contained array of { id, label, type, required, value } entries, with no separate lookup needed by the receiver.

The slash problem

IvyForms hook names contain forward slashes: ivyforms/form/after_submission. This caused two independent bugs that both had to be fixed separately:

Bug 1 — Discovery regex dropped them. The original character class [a-zA-Z0-9_\-\.] did not include /, so these hooks were never found by the static scan. Fix: add \/ to the character class.

Bug 2 — REST API 404s. Hook names with slashes were passed as literal URL path segments (/fswa/v1/schemas/ivyforms/form/after_submission), causing WordPress to fail route matching. Fix: encodeURIComponent() on the client side; on the server, expand the route regex to accept % and ., then rawurldecode() before sanitize_text_field() to recover the original hook name.

Users can reshape the payload before it is sent: rename fields, exclude noise, move nested values to the root. The mapping config is stored in the schema table:

PayloadTransformer::applyFieldMapping() first flattens the entire payload to dot-notation paths, applies explicit mappings, then optionally carries over everything else when includeUnmapped is true.

The Gravity Forms sub-field problem

Gravity Forms uses numeric sub-field IDs with dots in the key name: field 6.1, 6.2, etc. A key 6.1 in a PHP array, when represented in dot notation, is ambiguous — is this key 6 → key 1, or key 6.1?

The fix: dot characters inside array keys are escaped as \. when building paths. splitPath() uses a negative lookbehind to split only on unescaped dots:

Path args.0.6\.1 splits into ['args', '0', '6.1'] — the segment 6.1 is treated as a single key. Without this, Gravity Forms sub-fields would silently produce incorrect path resolution.

A few design decisions in this diagram are worth calling out explicitly: