Skip to main content

benecaster_webhook_payload

Filter Free

Filters an outbound webhook body once, when the event is queued — not when it is sent. The stored result is exactly what goes out on every attempt, retries included, and it is what the X-Benecaster-Signature header is computed over. Use it to add fields a receiving system needs, to remove fields you would rather not send to a third party, or to return null and send nothing for that event.

Removing personal data here is a legitimate use — the payload is about to leave your server for an external endpoint, and this is the last point at which you control what it contains.

It runs for every event Benecaster queues and for every add-on event sent with benecaster_send_webhook_event(). $payload['source'] tells them apart: "core" for Benecaster’s own events, the add-on’s catalog slug for an add-on’s. It does not run for webhook.test, which Send test event on Settings → Webhooks sends unfiltered.

Parameters

Name Type Default Description
$payload array — The body about to be queued: `event`, `delivery_id`, `source`, `schema_version`, the event's own keys, and `occurred_at`.
$event string — The event name, such as `subscription.activated` or an add-on's `{addon-slug}.{noun}.{verb}`.

Returns: array|null

Examples

Strip subscriber email from outbound webhooks

add_filter( 'benecaster_webhook_payload', function ( ?array $payload, string $event ): ?array {
    if ( null === $payload ) {
        return null;
    }
    unset( $payload['email'] );
    return $payload;
}, 10, 2 );

Notes

Because the body is fixed when the event is queued, a filter added or changed afterwards does not alter a delivery already waiting to be retried. Keep the body JSON-serialisable. For the full list of events and their keys, and how a receiver verifies the signature, see the recipes Mutate or block outgoing webhook payloads per event and Receive Benecaster webhooks safely.

Related Recipes

Need this built rather than just documented? See our services →