Skip to main content

benecaster_register_webhook_event()

Free 
benecaster_register_webhook_event( string $addon_slug, string $event, array $args = [] ): bool

Declares one event your add-on may send through the podcaster’s existing webhook — the same URL, signing secret, queue, retries, staging suppression and delivery log as Benecaster’s own events. Call it from the bootstrap you pass to benecaster_register_addon(); that is when Benecaster knows your add-on. Send the event with benecaster_send_webhook_event().

Settings → Webhooks lists each add-on’s registered events under the add-on’s name. There is no per-event switch: everything goes to the one URL, and the receiver filters on the event name or on the body’s source.

Parameters

Name Type Default Required Description
addon_slug string — Yes The slug your add-on registered with in benecaster_register_addon(). Either form works: podcast-workflow or benecaster-addon-podcast-workflow.
event string — Yes The event name, {addon-slug}.{noun}.{verb} under your add-on's catalog slug (no benecaster-addon- prefix): lowercase letters, digits and _ in the noun and verb, at most 191 characters. Example: podcast-workflow.guest.booked.
args array [] No label (string, translated by your add-on, shown on Settings → Webhooks beside the name; default '') and schema_version (positive int, default 1).

Return Value

Type: bool

true when the event is registered — registering the same name again from the same add-on replaces its $args — and false when it is refused. Every refusal is also reported with _doing_it_wrong().

Example

add_action( 'benecaster_boot', function ( \Benecaster\Container $container ) {
    benecaster_register_addon( 'podcast-workflow', static function (): void {
        benecaster_register_webhook_event( 'podcast-workflow', 'podcast-workflow.guest.booked', [
            'label' => __( 'A guest is booked', 'my-addon' ),
        ] );
    } );
} );

Notes

Refused when your add-on has not called benecaster_register_addon(); the name is not under your add-on's own prefix, so one add-on can never send under another's name; the name does not have exactly three dot-separated parts or uses other characters; or your slug would collide with one of Benecaster's own event families (subscription, token, subscriber, marketing_consent, webhook).

Raise schema_version only when you remove a key or change what one means. Adding a key is not a new version; a receiver may ignore keys it does not know. Worked example: the recipe Send your add-on's own events through Benecaster's webhook.

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