README

title	description
WP Webhook Framework	Entity-level webhooks for WordPress with scheduled and immediate delivery modes, retries, and failure monitoring.

WP Webhook Framework

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

Requires PHP 8.1+.

Ensure Action Scheduler is active (dependency is declared).

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

citation-media / wp-webhook-framework

Maintainers

Package info

Statistics

Security