Skip to main content

Mutate or block outgoing webhook payloads per event

Premium Intermediate

The outbound webhook queues subscription, token, engagement and consent events — and any add-on events — and POSTs them to the URL on Settings → Webhooks with a sha256= HMAC signature header. benecaster_webhook_payload runs once per event when it is queued, and the result is stored, so every retry sends the same body; your filter does not run again on a retry. Add custom keys, redact fields, or return null to skip dispatch entirely (for example, a per-show kill switch). The signature is computed over whatever your filter returns, so receivers verify against the post-filter body.

Notes

Every event and its keys are listed on the Outbound Webhooks page. Every body carries event, delivery_id, source ("core", or an add-on’s catalog slug for an add-on event), schema_version and occurred_at. Raw token strings are never included — only token_id.

The filter is not applied to webhook.test, which Send test event sends unfiltered. To check a receiver handles the filtered body, trigger a real event on a test show.

Code

<?php
// Add a tenant identifier to every outbound webhook.
add_filter( 'benecaster_webhook_payload', function ( ?array $payload, string $event ): ?array {
    if ( null === $payload ) {
        return null;
    }
    $payload['tenant'] = get_option( 'my_tenant_id' );
    return $payload;
}, 10, 2 );

// Skip webhook dispatch for a specific show.
add_filter( 'benecaster_webhook_payload', function ( ?array $payload ): ?array {
    if ( null === $payload || ( $payload['show_id'] ?? 0 ) === 42 ) {
        return null;
    }
    return $payload;
} );

View on GitHub →

Hooks Used

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