WP Webhook Framework – README

Entity-level webhooks for WordPress using Action Scheduler with optional immediate delivery mode. Sends POSTs for create/update/delete of posts, terms, and users. Meta changes trigger the entity update. ACF updates include field context. Features intelligent failure monitoring with email notifications, automatic blocking, and comprehensive filtering options.

Features

• Delivery mode control - Choose scheduled async delivery (default) or immediate synchronous first attempt
• Action Scheduler dispatch - 5s delay for queued webhooks with deduplication
• Automatic deduplication - Dispatcher-level on action+entity+id and meta-level per-request dedup for plugin hooks (ACF, Meta Box, etc.)
• Entity-aware delivery payloads - Derives post_type, taxonomy, and roles at send time
• Send-time enrichment - Adds REST URLs when available
• ACF integration - Adds field key/name context to meta changes
• Registry pattern - Extensible webhook system with custom configurations
• Notification system - Opt-in email alerts for failures, extensible notification handlers
• Failure monitoring - Automatic blocking after consecutive failures
• Comprehensive filtering - Control payloads, URLs, headers, and meta keys

Quick Start

Installation

composer require citation-media/wp-webhook-framework

Requirements

Requirement	Version
WordPress	6.7 or newer
PHP	8.1 or newer
Action Scheduler	3.7 or newer (declared as a Composer dependency)

WordPress 6.7 is a hard requirement: the dispatcher signals every delivery and configuration failure by throwing WP_Exception, which was added to core in 6.7.0. On older releases those throw sites raise an uncatchable Error: Class "WP_Exception" not found instead.

Action Scheduler comes bundled and is loaded by Service_Provider::register() — no separate plugin activation needed. If other plugins ship their own copy, Action Scheduler’s version manager initialises the newest one.

Caution

Call Service_Provider::register() while your plugin file loads, not from inside plugins_loaded. Action Scheduler registers itself on plugins_loaded at priority 0, so registering later loads it too late to initialise.

Basic Setup

// Initialize the framework
\juvo\WP_Webhook_Framework\Service_Provider::register();

Service_Provider::register() is idempotent, so separate plugins can call it independently while sharing the same library checkout.

Tip

If you are using a prefixer make sure to exclude this library. Due the strong typings used it will break plugins

See Configuration for detailed configuration options.

Usage Examples

Register Built-in Webhooks

No webhooks are active by default. Register what you need via the action:

use juvo\WP_Webhook_Framework\Webhooks\Post_Webhook;

add_action('wpwf_register_webhooks', function ($registry) {
    $post = new Post_Webhook();
    $post->webhook_url('https://api.example.com/posts')
         ->max_retries(3)
         ->timeout(60);
    $registry->register($post);
});

See Configuration for registry configuration and Custom Webhooks for creating your own webhooks.

Immediate Delivery Mode

use juvo\WP_Webhook_Framework\Delivery_Mode;
use juvo\WP_Webhook_Framework\Webhooks\Post_Webhook;

add_action('wpwf_register_webhooks', function ($registry) {
    $post = new Post_Webhook();
    $post->webhook_url('https://api.example.com/posts')
         ->delivery_mode(Delivery_Mode::IMMEDIATE)
         ->max_retries(2);
    $registry->register($post);
});

Immediate mode sends the first attempt in the current request. If it fails, retries are still queued asynchronously with exponential backoff.

Filter Payloads

// Prevent delete webhooks
add_filter('wpwf_payload', function($payload, $entity, $id) {
    if ($payload['action'] === 'delete') {
        return false; // Return false to prevent webhook
    }
    return $payload;
}, 10, 3);

See Hooks and Filters for all available hooks and filters.

Architecture Overview

Core Components

• Service_Provider - Singleton that bootstraps the framework
• Webhook_Registry - Manages webhook instances and initialization
• Webhook (abstract) - Base class for all webhooks
• Dispatcher - Schedules and sends HTTP requests via Action Scheduler
• Entity Handlers - Prepare payloads for posts, terms, users, and meta

Data Flow:

WordPress hook → Webhook → Handler::prepare_payload() → Webhook::emit() → Dispatcher
  ├─ scheduled mode: queue in Action Scheduler → process_scheduled_webhook() → HTTP POST
  └─ immediate mode: send now in current request → HTTP POST

Webhook Statefulness

Webhook instances are singletons and must remain stateless. Never store per-emission data as instance properties. Configuration (URL, timeout, headers) is set during init(). Payloads and dynamic data are passed directly to emit().

See Webhook Statefulness for detailed explanation and examples.

Payload Structure

Example post webhook payload:

{
  "action": "update",
  "entity": "post",
  "id": 123,
  "post_type": "post"
}

Persisted fields (event-time):

• Meta: meta_type, meta_key
• Meta: acf_field_key, acf_field_name (if ACF field)

Derived fields (when available at send time):

• Post: post_type
• Term: taxonomy
• User: roles[]
• rest_url

Failure Monitoring

• Email notifications on first failure after retries exhausted (opt-in via notifications(['blocked']))
• Automatic blocking after 10 consecutive failures within 1 hour
• Auto-unblock after 1 hour
• Success resets failure count and blocked status

See Failure Handling for configuration and customization.

Code Quality

• PHPCS Compliant - WordPress coding standards (WPCS 3.1)
• Type Safe - PHPStan level 6 static analysis
• i18n Ready - All user-facing strings internationalized
• Filterable - Extensive WordPress filter integration
• Well Documented - Comprehensive inline documentation

Commands

composer install              # Install dependencies
npm install                   # Install wp-env tooling
npm run wp-env:start          # Start WordPress test environment
npm run composer:install      # Install Composer dependencies inside wp-env
npm run test:phpunit          # Run application tests
npm run wp-env:stop           # Stop WordPress test environment
composer run-script phpstan   # Run static analysis
composer run-script phpcs     # Lint code
composer run-script phpcbf    # Auto-fix code style

Documentation

• Configuration - Webhook configuration methods, registry setup, and options
• Custom Webhooks - Creating custom webhooks, plugin integrations (WooCommerce, CF7, Gravity Forms)
• Hooks and Filters - All available hooks and filters with examples
• Failure Handling - Failure monitoring, retry mechanism, and blocking behavior
• Notifications - Notification system, opt-in pattern, and custom handlers
• Testing - wp-env application test suite, fixture plugins, and validation workflow
• Webhook Statefulness - Webhook statelessness rules and best practices