Skip to main content

benecaster_stripe_webhook_handlers

Filter Premium

Filters the map of Stripe event types to handler callables used by Benecaster’s Stripe webhook endpoints. Register a handler here to react to a Stripe event Benecaster does not itself handle, reusing the existing signature verification rather than exposing a second endpoint.

The filter feeds two endpoints. POST /benecaster/v1/stripe-webhook is the site-wide endpoint; POST /benecaster/v1/stripe-webhook/{show_uuid} serves a show running on its own Stripe account. Both resolve handlers through this same filter and pass the same arguments, so a handler registered here receives events from either without doing anything differently.

Which signing secret authenticates a request depends on the endpoint it arrived at: the site-wide endpoint uses the site-wide secret, and the per-show endpoint uses that show’s own secret, falling back to the site-wide one when the show has none.

Replacing a built-in handler is possible but rarely wise — Benecaster’s membership state depends on those handlers running. Add alongside them instead.

Parameters

Name Type Default Description
$handlers array — Handler callables keyed by Stripe event type. Each callable receives `( \Stripe\Event $event, \Benecaster\Payment\ListenerSupportRepository $repository )`. Return nothing to acknowledge the event (200), or a `WP_Error` to fail the delivery so Stripe retries it.

Returns: array

Examples

Handle an additional Stripe event

add_filter( 'benecaster_stripe_webhook_handlers', function ( array $handlers ): array {
    $handlers['customer.updated'] = static function ( \Stripe\Event $event ): void {
        $customer = $event->data->object;
        my_addon_sync_customer( $customer );
    };
    return $handlers;
} );

Notes

Handlers run after signature verification has passed. Keep them fast and idempotent.

To have Stripe retry an event, return a WP_Error. The endpoint answers with it, using its status data, or 500 when it has none, and Stripe redelivers later. Returning nothing acknowledges the event with 200. A handler that can fail this way must be safe to run twice for one event, because the retry runs it again. Don't throw to get a retry: return the error.

Do not route on the payload to work out which show an event belongs to at the endpoint level. Deriving the show from event metadata inside a handler is fine and remains the right approach, precisely because handlers run only after the signature has verified. The endpoint itself resolves the show from the URL instead — the request body is unauthenticated until the signature passes, so letting it nominate the show would let it nominate the secret it is checked against.

A handler is given a \Stripe\Event object, not an array. It supports array access because the Stripe SDK's objects do, but type-hinting the parameter as array will throw a TypeError.

Related Recipes

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