README

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 - Based on action+entity+id
Entity-aware payloads - Includes post_type, taxonomy, or roles
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

Ensure Action Scheduler is active (dependency is declared).

Basic Setup

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

Configuration

// wp-config.php
define('WP_WEBHOOK_FRAMEWORK_URL', 'https://api.example.com/webhook');

See Configuration for detailed configuration options.

Usage Examples

Configure Built-in Webhooks

$registry = \Citation\WP_Webhook_Framework\Service_Provider::get_registry();

$post_webhook = $registry->get('post');
if ($post_webhook) {
    $post_webhook->webhook_url('https://api.example.com/posts')
                 ->max_retries(3)
                 ->max_consecutive_failures(5)
                 ->timeout(60)
                 ->notifications(['blocked']); // Enable email notifications
}

Create Custom Webhook

class Custom_Webhook extends \Citation\WP_Webhook_Framework\Webhook {
    
    public function __construct() {
        parent::__construct('my_custom_webhook');
        
        $this->max_retries(3)
             ->max_consecutive_failures(3)
             ->timeout(30)
             ->webhook_url('https://api.example.com/custom')
             ->headers(['Authorization' => 'Bearer token123']);
    }
    
    public function init(): void {
        if (!$this->is_enabled()) {
            return;
        }
        
        add_action('my_custom_action', [$this, 'handle_action'], 10, 1);
    }
    
    public function handle_action($data): void {
        $payload = ['custom_data' => $data, 'timestamp' => time()];
        $this->emit('action_triggered', 'custom', $data['id'], $payload);
    }
}

// Register the webhook
add_action('wpwf_register_webhooks', function($registry) {
    $registry->register(new Custom_Webhook());
});

See Custom Webhooks for detailed webhook creation guide.

Filter Payloads

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

// Add custom data to user webhooks
add_filter('wpwf_payload', function($payload, $entity, $id) {
    if ($entity === 'user') {
        $user = get_userdata($id);
        $payload['email'] = $user->user_email;
    }
    return $payload;
}, 10, 3);

See Hooks and Filters for all available hooks and filters.

Architecture Concepts

Webhook Statefulness

Important: Webhook instances are singletons and must remain stateless. Never store per-emission data as instance properties.

Stateless (configuration):

// Set once during __construct()
$this->webhook_url('https://api.example.com')
     ->max_consecutive_failures(5);

Stateful (emission data):

// Pass directly to emit() - NEVER store on instance
$this->emit('update', 'post', $post_id, $payload);

See Webhook Statefulness for detailed explanation.

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 → HTTP POST

Payload Structure

Example webhook payload:

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

Entity-specific invariants:

Post: post_type
Term: taxonomy
User: roles[]
Meta: acf_field_key, acf_field_name (if ACF field)

Failure Monitoring

Email notifications on first failure after retries exhausted
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

citation-media / wp-webhook-framework

Maintainers

Details