Search by

arraypress / wp-webhooks

arraypress

This package is abandoned and no longer maintained. No replacement package was suggested.

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.

Package info

github.com/arraypress/wp-webhooks

Homepage

pkg:composer/arraypress/wp-webhooks

Statistics

Installs: 21

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-08-25 21:29 UTC

This package is auto-updated.

Last update: 2026-11-18 10:56:01 UTC


README

This library has moved. It is now part of sugarcommerce/webhooks (namespace SugarCommerce\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