benecaster_stripe_webhook_handlers
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 )`. |
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 — Stripe retries on non-2xx responses, so a slow or throwing handler produces duplicate deliveries.
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.
Need this built rather than just documented? See our services →