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 secrets authenticate a request depends on the endpoint it arrived at. The site-wide endpoint accepts a delivery signed with any of the site’s secrets: the one pasted by hand, and the test-mode and live-mode ones Set Up Webhook saved. The per-show endpoint accepts that show’s own set the same way, falling back to the site’s when the show has none.
The events you register here are subscribed for you. When a podcaster presses Set Up Webhook on Settings → Payments or a show’s Payments tab, the endpoint Benecaster creates in their Stripe account carries Benecaster’s own events plus every event type keyed in this filter, so your handler’s event is delivered without the podcaster ticking it in Stripe. An endpoint the podcaster created by hand still needs the event added by hand; say so in your add-on’s setup instructions, or point them at the button.
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.
Need this built rather than just documented? See our services →