PHPackages                             citation-media/wp-webhook-framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. citation-media/wp-webhook-framework

ActiveLibrary

citation-media/wp-webhook-framework
===================================

Entity-level webhook framework for WordPress using Action Scheduler.

1.1.2(2mo ago)2161↑130.8%[3 issues](https://github.com/JUVOJustin/wp-webhook-framework/issues)[5 PRs](https://github.com/JUVOJustin/wp-webhook-framework/pulls)GPL-2.0-or-laterPHPPHP >=8.1CI passing

Since Aug 20Pushed 1mo agoCompare

[ Source](https://github.com/JUVOJustin/wp-webhook-framework)[ Packagist](https://packagist.org/packages/citation-media/wp-webhook-framework)[ RSS](/packages/citation-media-wp-webhook-framework/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (8)Versions (14)Used By (0)

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

[](#wp-webhook-framework)

[![Quality Check](https://github.com/JUVOJustin/wp-webhook-framework/actions/workflows/quality-check.yml/badge.svg)](https://github.com/JUVOJustin/wp-webhook-framework/actions/workflows/quality-check.yml)[![Integration Tests](https://github.com/JUVOJustin/wp-webhook-framework/actions/workflows/integration-tests.yml/badge.svg)](https://github.com/JUVOJustin/wp-webhook-framework/actions/workflows/integration-tests.yml)

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

[](#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
-----------

[](#quick-start)

### Installation

[](#installation)

```
composer require citation-media/wp-webhook-framework
```

Requires PHP 8.1+.

Ensure Action Scheduler is active (dependency is declared).

### Basic Setup

[](#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](./docs/configuration.mdx) for detailed configuration options.

Usage Examples
--------------

[](#usage-examples)

### Register Built-in Webhooks

[](#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](./docs/configuration.mdx) for registry configuration and [Custom Webhooks](./docs/custom-webhooks.mdx) for creating your own webhooks.

### Immediate Delivery Mode

[](#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

[](#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](./docs/hooks-and-filters.mdx) for all available hooks and filters.

Architecture Overview
---------------------

[](#architecture-overview)

### Core Components

[](#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-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](./docs/webhook-statefulness.mdx) for detailed explanation and examples.

Payload Structure
-----------------

[](#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
------------------

[](#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](./docs/failure-handling.mdx) for configuration and customization.

Code Quality
------------

[](#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
--------

[](#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
-------------

[](#documentation)

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

###  Health Score

40

—

FairBetter than 87% of packages

Maintenance74

Regular maintenance activity

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 63.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~46 days

Total

5

Last Release

76d ago

Major Versions

0.1.0 → 1.0.02026-02-13

PHP version history (2 changes)0.1.0PHP >=8.0

1.0.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/32efecde6068b3efb5bd8edbfc59500f23c7047b43f7846790925f73e23317a6?d=identicon)[JUVOJustin](/maintainers/JUVOJustin)

---

Top Contributors

[![JUVOJustin](https://avatars.githubusercontent.com/u/30726576?v=4)](https://github.com/JUVOJustin "JUVOJustin (38 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (22 commits)")

---

Tags

webhookswordpress

###  Code Quality

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/citation-media-wp-webhook-framework/health.svg)

```
[![Health](https://phpackages.com/badges/citation-media-wp-webhook-framework/health.svg)](https://phpackages.com/packages/citation-media-wp-webhook-framework)
```

###  Alternatives

[wp-pay/core

Core components for the WordPress payment processing library.

29119.8k97](/packages/wp-pay-core)[wp-pay-extensions/gravityforms

Gravity Forms driver for the WordPress payment processing library.

1133.3k2](/packages/wp-pay-extensions-gravityforms)[typerocket/core

The TypeRocket Pro Core.

3920.9k1](/packages/typerocket-core)[rankmath/seo-by-rank-math

Rank Math is the most powerful way to get BEST WordPress SEO tools added to your website.

1252.0k](/packages/rankmath-seo-by-rank-math)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)