README

title	description
WP Webhook Framework	Entity-level webhooks for WordPress using Action Scheduler. Sends non-blocking POSTs for create/update/delete of posts, terms, and users.

WP Webhook Framework

Entity-level webhooks for WordPress using Action Scheduler. Sends non-blocking 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

Action Scheduler dispatch - 5s delay, non-blocking async delivery
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();

:::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.

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 → Action Scheduler → Dispatcher::process_scheduled_webhook() → Handler::prepare_delivery_payload() → 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
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
Webhook Statefulness - Webhook statelessness rules and best practices

citation-media / wp-webhook-framework

Maintainers

Details