arraypress / wp-webhooks
Signed webhooks for WordPress: an endpoint store, an event catalogue and a dispatcher on Action Scheduler, with Stripe-compatible signatures, a status-aware retry policy and refusal of private-network addresses.
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/webhooks(namespaceSugarCommerce\Webhooks, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
WordPress Webhooks
Send webhooks from a plugin that receivers can verify, retry the ones worth retrying, and stop posting to endpoints that have gone.
What it does
A plugin that tells other systems what happened needs the same parts every
time: a list of endpoints on a settings screen, a catalogue of events to tick,
a queue so a slow receiver never holds up a checkout, retries that know a 503
from a 422, a signature, and a check that the address the site owner typed in
is not 169.254.169.254. This is all of them, on Action Scheduler and
WordPress's own HTTP API.
The signature is Stripe's scheme, so receivers can verify it with code they
already have. It signs timestamp.payload, sends both in the header, and
rejects anything outside a tolerance window on the way back in.
Features
- Post an event to every endpoint that ticked it, queued and signed
- Let add-ons add their own events to the catalogue, with labels and descriptions
- Retry outages and rate limits on a stated schedule, honouring
Retry-After - Switch off an endpoint that has failed for a day, and back on when a test answers
- Refuse addresses inside the server's network: private, loopback, link-local, IPv6 included
- Erase a person from deliveries still waiting in the queue
- Verify a received webhook in constant time, with replay protection
- Rotate secrets without dropping deliveries
Installation
composer require arraypress/wp-webhooks
Quick start
use ArrayPress\Webhooks\Dispatcher; $webhooks = new Dispatcher( [ 'prefix' => 'myshop', 'header' => 'MyShop', // MyShop-Signature, MyShop-Event 'user_agent' => 'MyShop/' . MYSHOP_VERSION, 'events' => fn() => [ 'order.completed' => __( 'Order completed', 'myshop' ), 'order.refunded' => [ 'label' => __( 'Order refunded', 'myshop' ), 'description' => __( 'Sent for a full or part refund.', 'myshop' ), ], ], 'endpoints' => 'myshop_webhook_endpoints', // an option of its own ] ); $webhooks->init(); // every request: attaches the delivery job add_action( 'myshop_order_completed', function ( $order ) use ( $webhooks ) { $webhooks->dispatch( 'order.completed', [ 'id' => $order->id, 'total' => $order->total ] ); } );
Each endpoint that wants the event gets one queued delivery of the same body:
{"id":"evt_3f2a…","type":"order.completed","created":1767312000,"test":false,"data":{"id":1001,"total":4900}}
Names a plugin owns
Everything an add-on or a receiver can see is built from prefix and
header, so several plugins use this side by side:
| What | Name |
|---|---|
Queued action, args [ endpoint id, type, body, attempt ] |
{prefix}_send_webhook in Action Scheduler group group (the prefix) |
| Filters | {prefix}_webhook_events, {prefix}_webhook_data, {prefix}_webhook_failure_limit, {prefix}_webhook_failure_period |
| Actions | {prefix}_webhook_failed, {prefix}_webhook_switched_off |
| Option, the record of failures | {prefix}_webhook_health (or health_option) |
| Headers | {header}-Signature, {header}-Event |
Endpoints
Use endpoints()->sanitize() as the setting's sanitize callback. It keeps
http(s) addresses with a host, mints an id (we_…) once and keeps it — a
queued delivery remembers its endpoint by id — and mints a whsec_… secret
when the field is left empty. Ticking no events means all of them.
Endpoints kept inside another settings array take read/write callables:
'endpoints' => [ 'read' => fn() => myshop_get_option( 'webhook_endpoints', [] ), 'write' => fn( array $rows ) => myshop_update_option( 'webhook_endpoints', $rows ), ],
Retries
A minute, five minutes, half an hour, two hours: five tries, to the second.
A refusal (4xx, a 410 most of all) is final; no answer, a 408, a 429 or a 5xx
is tried again. A 429 or 503 with Retry-After (seconds or an HTTP-date)
waits that long instead, up to a day. Pass 'retry' => RetryPolicy::fixed( … )
or new RetryPolicy() for another schedule. Without Action Scheduler an
event is sent once, there and then.
A dead endpoint is switched off
Fifteen failures in a row that span at least a day turn the endpoint's own
Active toggle off and fire {prefix}_webhook_switched_off. Both conditions,
because twenty failures can be one minute of a restart. A success resets the
count. breaker()->switched_off() lists them for a notice or Site Health.
It comes back when someone turns Active on and saves, or sends it a test:
$result = $webhooks->test( $endpoint_id ); // a signed `ping`, now, never queued // [ 'found' => true, 'ok' => true, 'status' => 200, 'error' => '', 'url' => '…' ]
An answered test switches it back on. With endpoints in read/write
callables, call breaker()->saved( $old_rows, $new_rows ) when they are saved.
Addresses inside the network
Every delivery goes through SafeUrl, on top of wp_safe_remote_post().
Every A and AAAA answer must be public — loopback, RFC 1918, link-local, the
metadata service, unique-local and NAT64/6to4 forms of IPv6, in any spelling.
URLs with credentials or odd hosts are refused, curl is pinned to the address
that was checked, and redirects (none followed by default; 'redirects' => 3)
are re-checked hop by hop. WordPress's http_request_host_is_external filter
still lets a development host through.
Erasing a person from the queue
A queued delivery carries its whole body, a buyer's email in it. For a privacy eraser:
$webhooks->queued()->rewrite( $email, function ( array $event ) use ( $email ): ?array { if ( ( $event['data']['email'] ?? '' ) !== $email ) { return null; // only mentions them: leave it } $event['data']['email'] = ''; return $event; } );
Pending ones are re-queued for the same moment with the new body; finished ones are deleted.
Receiving
use ArrayPress\Webhooks\Signature; $result = Signature::verify( $raw_body, $header, $secret ); // the raw body, never re-encoded if ( ! $result->valid ) { status_header( 400 ); // log $result->reason; do not echo it exit; }
Several v1= values in one header are all checked, which is how a secret is
rotated without dropping deliveries.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
- Action Scheduler, for queued delivery (see
arraypress/wp-register-cron)
License
GPL-2.0-or-later