Skip to main content

Action Hooks Reference

All action hooks provided by Benecaster. Each hook name links to its reference page with full parameter docs, usage notes, and code examples.

Hooks are not a paid feature — we don’t charge for them and none of them is gated behind a purchase. Hooks marked Premium sit on code paths that only run on a licensed install, so on an unlicensed site they simply never fire; there is nothing for them to act on. Everything else fires on any install.


Show Lifecycle

Fire as a show is created, edited, trashed, or permanently deleted.

Hook Description
benecaster_show_created Fires after a new show is saved for the first time
benecaster_show_updated Fires after an existing show is updated
benecaster_show_trashed Fires after a show is moved to trash; slot recovery happens immediately — the trashed show no longer counts toward the site’s show limit
benecaster_show_deleted Fires before a show is permanently deleted

Episode Lifecycle

Fire as an episode moves through creation, edits to its fields, references, and custom field values, publish/unpublish transitions, and deletion.

Hook Description
benecaster_episode_created Fires after a new episode is saved for the first time
benecaster_episode_updated Fires after an existing episode is updated (post-table fields only)
benecaster_episode_meta_updated Fires after episode meta is saved; includes before/after diff of changed keys
benecaster_episode_references_updated Fires after a reference entry is created, updated, or deleted on an episode
benecaster_episode_field_values_updated Fires after custom field values are saved on an episode
benecaster_episode_published Fires when an episode’s post status transitions to publish
benecaster_episode_unpublished Fires when an episode’s post status leaves publish
benecaster_episode_deleted Fires before an episode is permanently deleted
benecaster_episode_move_before Fires when an episode is about to move to another show, after every check and before anything is written
benecaster_episode_move_after Fires after an episode has moved to another show and both feed caches are cleared
benecaster_episode_references_moved Fires during an episode move, with a map of which reference library item each cited item became in the new show
benecaster_episode_note_added Fires after a production note is added to an episode via benecaster_add_episode_note()

Subscription Lifecycle

Fire when a subscriber’s membership changes state on the connected bridge — activated, cancelled, moved to a different tier, renewed, or failed to pay.

Hook Description
benecaster_subscription_activated Fires when a subscriber becomes active on any bridge
benecaster_subscription_synced Fires when Sync existing members links somebody who already belonged to the membership plugin, instead of benecaster_subscription_activated; receives $user_id, $show_id, $tier_slug, $started_at
benecaster_subscription_cancelled Fires when any bridge reports a subscription has been cancelled
benecaster_subscription_tier_changed Fires when a built-in-membership subscriber moves from one tier to another, or an admin changes their tier; sends the Tier Change email. Not fired for a membership plugin’s plan change
benecaster_subscription_tier_moved Fires once whenever a subscriber holds a different tier, whatever reported it — membership plugin, built-in membership or admin; sends nothing. Rank the move with benecaster_compare_tiers()
benecaster_subscription_free_switch_scheduled Fires when a built-in-membership subscriber chooses the show’s free plan; the move lands at their renewal
benecaster_subscription_free_switch_landed Fires when that move lands: the subscriber is on the free tier with the same feed URL
benecaster_subscription_free_switch_cancelled Fires when that move is withdrawn before it lands, by the subscriber or by cancelling their membership
benecaster_subscription_renewed Fires on each successful recurring payment after the initial subscription
benecaster_subscription_payment_failed Fires when a subscriber’s payment fails after the grace period elapses

Token Lifecycle

Fire around the feed token that gives a subscriber access — generated, accessed, reset, revoked, or presented invalid.

Hook Description
benecaster_token_generated Fires immediately after a new subscriber token is created
benecaster_token_accessed Fires on every valid feed request after the token is verified
benecaster_feed_link_requested Fires when a podcaster emails a subscriber the feed URL they already have; nothing is reset
benecaster_token_reset Fires after a subscriber’s token is reset and a new one is active
benecaster_token_reset_send_email Fires when admin selects “Reset and send email” (single or bulk) — but not if the show’s Feed URL reset email is switched off. To see every admin reset regardless, hook benecaster_token_reset instead
benecaster_token_revoked Fires when a subscriber’s token is revoked; $reason says why (a cancellation, a podcaster’s removal, a grant ending)
benecaster_token_invalid Fires when a feed request presents a token that fails validation
benecaster_subscriber_no_active_membership Fires when a valid token is presented but the subscriber has no active mapped membership tiers

Feed

Fire around the moment a feed’s RSS XML is output, for code that needs to act right before or after the response body rather than filter its contents.

Hook Description
benecaster_feed_before_render Fires after HTTP headers are sent but before feed XML is output
benecaster_feed_after_render Fires immediately after feed XML is echoed to output

Feed Cache

Trigger and react to clearing the compiled-feed cache. Every feed is cached, your public feed included, so both hooks fire on every install.

Hook Description
benecaster_clear_feed_cache Call this action to trigger a feed cache clear (global, show-scoped, or tier-scoped)
benecaster_feed_cache_cleared Fires after any feed cache clear completes, regardless of what triggered it

Custom Fields

Fires after a custom field value is persisted, for add-ons that need to react to a specific field changing.

Hook Description
benecaster_field_value_saved Fires after a custom field value is written to the database

Setup and Configuration

Fire around first-run setup and bridge configuration — completing the setup wizard, saving a bridge selection, and clearing stale <itunes:new-feed-url> redirects.

Hook Description
benecaster_setup_wizard_completed Fires once when the setup wizard is completed
benecaster_wizard_late_step_completed Fires when an add-on’s setup step, requested after setup, is completed for a show
benecaster_wizard_late_step_declined Fires when an add-on’s setup step, requested after setup, is declined for a show
benecaster_bridge_connected Fires each time an admin saves a bridge selection
benecaster_redirect_expiry_run Fires after expired <itunes:new-feed-url> redirect tags are removed

Bridge and Tier Events

Fire when the mapping between a membership plugin’s levels and Benecaster’s tiers changes, or when the bridge itself is switched.

Hook Description
benecaster_tier_unmapped Fires when a tier detected by the bridge has no Benecaster tier mapping; fires from both real-time tier-save events and the daily sync fallback
benecaster_bridge_switched Fires after the Bridge Switch Wizard completes; new tier mappings saved (none when switching to built-in membership) and active bridge updated
benecaster_tier_map_updated Fires after PUT /bridge/tier-map saves a batch of tier mappings from the Tier Mapping board or list view; not from the Bridge Switch Wizard
benecaster_bridge_new_levels_detected Fires when the tier mapping screen finds at least one membership level not in the stored seen-set; built-in admin notice reacts automatically

SSP / PowerPress Import Events

Fire while episodes are imported from the Seriously Simple Podcasting or PowerPress plugins, per-episode and per-batch.

Hook Description
benecaster_ssp_import_after Fires after all SSP episodes have been processed for a show; includes runs with zero new drafts
benecaster_ssp_episode_imported Fires after each individual SSP draft episode is created; $ssp_post provides the original post
benecaster_powerpress_import_after Fires after all PowerPress episodes have been processed for a show; includes runs with zero new drafts
benecaster_powerpress_episode_imported Fires after each individual PowerPress draft episode is created; $pp_post provides the original post

Analytics and Data Management

Fire when shadow records (imported patron placeholders — see Show Settings Reference) are created from a Patreon upload and when the nightly purge clears expired ones.

Hook Description
benecaster_patreon_shadow_records_created Fires after a Patreon CSV upload in a show’s Visibility settings creates shadow records; only when at least one valid email was found
benecaster_shadow_records_purged Fires after each nightly shadow record purge run; fires even when $count === 0; threshold controlled by benecaster_shadow_record_expiry_days

Subscriber Engagement

Fire as Benecaster tracks whether a subscriber’s podcast app is actively polling their feed — first poll, never starting, going inactive, and coming back. All four pass the token’s stored tier — follower for a follower.

Hook Description
benecaster_token_first_accessed Fires the first time a subscriber’s podcast app polls a valid feed token — confirms the app is configured and working
benecaster_subscriber_feed_inactive Fires once per inactivity event when an active subscriber stops polling past the show’s Feed inactivity threshold
benecaster_subscriber_feed_reactivated Fires when a previously inactive subscriber polls their feed again
benecaster_subscriber_never_accessed Fires once when a subscriber was issued a feed URL and has still not polled it after the grace window (7 days by default)

Templates — Show Page

Bracket each section of the public show page — header, subscribe links, tier listing, embedded episode list, and stats — for inserting custom markup before or after.

Hook Description
benecaster_before_show_render Fires before the show page wrapper renders; receives $show_id (int)
benecaster_after_show_render Fires after the show page wrapper closes; receives $show_id (int)
benecaster_before_show_header Fires before the show header (title, artwork, description) renders
benecaster_after_show_header Fires after the show header closes
benecaster_before_show_subscribe_links Fires before the subscribe links block renders
benecaster_after_show_subscribe_links Fires after the subscribe links block closes
benecaster_before_show_tiers Fires before the tier listing renders
benecaster_after_show_tiers Fires after the tier listing closes
benecaster_before_show_episode_list Fires before the embedded episode list renders
benecaster_after_show_episode_list Fires after the embedded episode list closes
benecaster_before_show_stats Fires before the public stats block renders (hidden by default — enable via benecaster_show_stats_visible filter)
benecaster_after_show_stats Fires after the public stats block closes
benecaster_show_stats_items Fires inside the stats block; echo additional <li> items to add custom stats

Templates — Locked State

Bracket the messages shown to visitors who can’t access an episode — the generic locked message, the upgrade prompt for logged-in subscribers at the wrong tier, and the login prompt for logged-out visitors.

Hook Description
benecaster_before_locked_message Fires before the locked state message renders in the player or content area; receives $episode_id (int), $show_id (int)
benecaster_after_locked_message Fires after the locked state message closes; receives $episode_id (int), $show_id (int)
benecaster_before_upgrade_prompt Fires before the upgrade prompt renders (shown to logged-in subscribers at wrong tier); receives $episode_id (int), $show_id (int), $required_tier (string), $user_tier (string)
benecaster_after_upgrade_prompt Fires after the upgrade prompt closes; same args as above
benecaster_before_login_prompt Fires before the login prompt renders (shown to logged-out visitors); receives $episode_id (int), $show_id (int)
benecaster_after_login_prompt Fires after the login prompt closes; receives $episode_id (int), $show_id (int)

Templates — Episode Archive

Bracket the episode archive listing and each part of an individual episode card — artwork, title, meta, excerpt, player, and locked state — for inserting custom markup around them.

Hook Description
benecaster_before_episode_archive Fires before the archive wrapper renders
benecaster_after_episode_archive Fires after the archive wrapper closes
benecaster_before_archive_header Fires before the archive header (title + description) renders
benecaster_after_archive_header Fires after the archive header closes
benecaster_before_archive_filters Fires before the episode filter bar renders
benecaster_after_archive_filters Fires after the episode filter bar closes
benecaster_before_archive_pagination Fires before pagination renders
benecaster_after_archive_pagination Fires after pagination closes
benecaster_before_archive_no_results Fires before the empty-state message renders
benecaster_after_archive_no_results Fires after the empty-state message closes
benecaster_before_episode_card Fires before each episode card renders; receives (int $episode_id, bool $can_access)
benecaster_after_episode_card Fires after each episode card closes; receives (int $episode_id, bool $can_access)
benecaster_before_episode_card_artwork Fires before the artwork section of an episode card
benecaster_after_episode_card_artwork Fires after the artwork section of an episode card
benecaster_before_episode_card_title Fires before the title section of an episode card
benecaster_after_episode_card_title Fires after the title section of an episode card
benecaster_before_episode_card_meta Fires before the meta section of an episode card (episode number, duration, pub date)
benecaster_after_episode_card_meta Fires after the meta section of an episode card
benecaster_before_episode_card_excerpt Fires before the excerpt section of an episode card
benecaster_after_episode_card_excerpt Fires after the excerpt section of an episode card
benecaster_before_episode_card_player Fires before the player section of an episode card
benecaster_after_episode_card_player Fires after the player section of an episode card
benecaster_before_episode_card_locked Fires before the locked state section of an episode card
benecaster_after_episode_card_locked Fires after the locked state section of an episode card

Admin Subscriber Actions

Fire when a podcaster manually revokes a subscriber’s access or overrides their tier from the Benecaster admin.

Hook Description
benecaster_subscriber_access_revoked Fires when an admin manually revokes a subscriber’s access via the dashboard
benecaster_subscriber_tier_overridden Fires when an admin manually overrides a subscriber’s tier via the dashboard

Email Events

Fire around dispatch of any Benecaster email, a test send and a broadcast, and around a subscriber’s opt-out state, for logging, monitoring send failures, or reacting to unsubscribes.

Hook Description
benecaster_before_email_send Fires before any Benecaster email is dispatched, except a test send; use for logging (type-specific variant: benecaster_before_email_send_{type})
benecaster_after_email_send Fires after any Benecaster email is queued, not delivered, except a test send; carries the queue row id (type-specific variant: benecaster_after_email_send_{type})
benecaster_test_email_queued Fires when a test send is queued, in place of the before- and after-send actions
benecaster_before_broadcast_send Fires once per broadcast, in the request that sent it, with its recipients and before any is queued
benecaster_after_broadcast_send Fires once per broadcast, from the background batch that queues its last recipient, with how many were queued, suppressed and skipped
benecaster_email_send_failed Fires when an email could not be queued
benecaster_email_suppressed Fires when benecaster_email_should_send refuses a send, with the reason
benecaster_email_unsubscribed Fires after a subscriber’s email opt-out is recorded
benecaster_email_resubscribed Fires when a subscriber re-opts in to emails after previously opting out; Benecaster has no screen that triggers it
benecaster_email_queue_job_complete Fires when all rows in a job group reach terminal status (sent or failed); use to update migration or broadcast status records

Fires when a person’s answer to an add-on’s marketing-consent checkbox is recorded or changes. Benecaster asks only when an add-on asks it to, and never sends marketing email itself.

Hook Description
benecaster_marketing_consent_changed Fires after a consent answer is recorded and something changed — a first answer, a different answer, or an answer becoming verified. Read the current answer with benecaster_get_marketing_consent()

Integration Actions

Fire around an add-on’s handler when an outside system — Zapier, Make, a CRM — calls it through POST /wp-json/benecaster/v1/actions. Neither fires for a replay of an earlier request.

Hook Description
benecaster_before_integration_action_run Fires after every check passes, just before the action’s handler runs
benecaster_after_integration_action_run Fires after the handler returns, with its result or the WP_Error it refused or failed with

Subscriber Account (Front End)

Bracket each section of the [benecaster_account] shortcode — subscription, feed URL, token reset, app links, and QR code — for add-ons that extend the subscriber account page.

Hook Description
benecaster_before_account Fires before the account shortcode wrapper renders; receives $user_id (int)
benecaster_after_account Fires after the account shortcode wrapper closes; receives $user_id (int)
benecaster_before_account_subscription Fires before the subscription section renders; receives $show_id (int), $user_id (int)
benecaster_after_account_subscription Fires after the subscription section closes; receives $show_id (int), $user_id (int)
benecaster_before_account_feed_url Fires before the feed URL section renders; receives $show_id (int), $user_id (int)
benecaster_after_account_feed_url Fires after the feed URL section closes; receives $show_id (int), $user_id (int)
benecaster_before_account_token_reset Fires before the token reset section renders; receives $show_id (int), $user_id (int)
benecaster_after_account_token_reset Fires after the token reset section closes; receives $show_id (int), $user_id (int)
benecaster_before_account_app_links Fires before the app links section renders; receives $show_id (int), $user_id (int)
benecaster_after_account_app_links Fires after the app links section closes; receives $show_id (int), $user_id (int)
benecaster_before_account_qr_code Fires before the QR code section renders; receives $show_id (int), $user_id (int)
benecaster_after_account_qr_code Fires after the QR code section closes; receives $show_id (int), $user_id (int)
benecaster_before_account_email_preferences Fires before the Email preferences section; receives $show_id (int), $user_id (int)
benecaster_after_account_email_preferences Fires after the Email preferences section, the last built-in section of a subscription card; receives $show_id (int), $user_id (int)
benecaster_account_sections Fires at the end of each subscription card inside [benecaster_account]; add-ons echo additional HTML sections; receives $show_id (int), $user_id (int)

License Events

Fire as the daily license validation cron runs — successful validation, explicit rejection, an unreachable server, the payment-failed grace window, and the hard limit reached after sustained failures.

(All hooks in this section are Premium — fire only on paid plans or when license validation runs — except the two marked Free)

The daily run validates each connected show in turn. Hooks that report one validation end with a $show_uuid argument naming that show; pass it to benecaster_get_license_plan() when you read the license back. The two day-30 cutoff hooks end with $show_uuids instead, every connected show on the license that was cut off. A listener registered for fewer arguments keeps working.

Hook Description
benecaster_license_validated Fires when the daily validation cron receives a valid response from the license server; receives $response (array), $show_uuid (string)
benecaster_license_invalid Fires when validation returns an explicit rejection (status: "invalid") from a reachable server; receives $response (array), $show_uuid (string)
benecaster_license_plan_changed Free. Fires when a validation changes the cached plan, and only then; receives $from (string), $to (string), $show_uuid (string)
benecaster_license_expiring Fires on each validation while the license is within 30 days of expiry; receives $days_remaining (int), $expires_at (string), $show_uuid (string)
benecaster_over_limit_flags_evaluated Free. Fires after each validation once subscribers over the plan’s limits are flagged; receives $count (int), $ids (int[]), $show_uuid (string)
benecaster_license_grace_started Fires when a failed payment opens the 30-day grace window; receives $started_at (int), $reason (string), $show_uuid (string)
benecaster_license_payment_grace_hard_cutoff Fires once on day 30 of an unpaid grace window, when subscriber access is cut off; receives $cutoff_at (int), $token_count (int), $show_uuids (string[])
benecaster_license_grace_expired Fires straight after the day-30 cutoff, for older listeners; receives $started_at (int), $show_uuids (string[])
benecaster_license_grace_recovered Fires when the license goes valid again and closes a grace window; receives $started_at (int), $duration_seconds (int), $show_uuid (string)
benecaster_license_payment_grace_recovered Fires when a recovery lifts a day-30 cutoff and restores subscriber access; receives $restored_count (int), $started_at (int), $show_uuid (string)
benecaster_validation_failure Fires every day the license server is unreachable; passes the cumulative consecutive failure day count
benecaster_license_hard_limit_reached Fires after 30 consecutive days of server-unreachable failures; premium features are restricted until the next successful validation
benecaster_license_free_threshold_warning Fires when a site’s paying subscriber count reaches 80% of its plan’s limit, at most once per calendar month. A notice cadence, not a plan-change signal

Seven license-enforcement action names do not exist in Benecaster and never fire: benecaster_license_overage_month_1, _month_2, _cleared, benecaster_license_free_bump_confirmed, benecaster_license_downgrade_locked, benecaster_license_auto_upgrade_fired and benecaster_license_downgrade_lock_expired. They are named here because a callback attached to one of them simply never runs — nothing errors — so a license hook that seems dead is worth checking against this page. The premises they describe are not how licensing works: overage is counted on a rolling window held by the license server, which the plugin cannot see, and there is no downgrade lock.


Data Export

Fire around generation of the “Your Data” XLSX export a subscriber can download.

Hook Description
benecaster_before_export Fires before XLSX file generation begins for the “Your Data” export
benecaster_after_export Fires after the export XLSX is written to a temporary file, before the download response is sent

Shortcode Extension

Lets an add-on echo custom HTML inside each tier card rendered by [benecaster_subscribe].

Hook Description
benecaster_subscribe_tier_content Fires inside each tier card in [benecaster_subscribe] on a membership-plugin show, after the price and Subscribe button; echo a description, never a second price or button. Passes the card’s tier slug, show ID, and the plugin’s level ID and plugin slug (register with 10, 4 for the last two)

Front-end Scripts and Styles

Benecaster registers its front-end script and style handles on init, not on wp_enqueue_scripts, so they exist in wp-admin, the block editor and preview requests as well as on the front end. Each file is still added to a page only when the shortcode that needs it renders there.

To keep a Benecaster file off a page, call wp_dequeue_style() or wp_dequeue_script() on its handle. Removing a Benecaster callback from wp_enqueue_scripts with remove_action() does nothing. The handle names, and how to load them into the block editor, are in Load Benecaster’s front-end styles into the block editor.


Add-on Hooks

These fire only while the named add-on is installed and active. Benecaster’s own actions are above.

Add-on Manager

Fire as the Add-on Manager downloads, checks and installs add-ons, and updates them or itself. Each page lists the order the pairs fire in. Nothing a callback returns is read.

Hook Description
benecaster_manager_package_before_verify Fires before a package is downloaded and its signature checked, for an add-on update, an install, or the Manager’s own update
benecaster_manager_package_verified Fires when a package passed the signature check
benecaster_manager_package_rejected Fires when a package was refused; nothing is unpacked. The event worth an alert
benecaster_manager_addon_before_install Fires before an add-on is installed from a Ready to install card
benecaster_manager_addon_installed Fires when an add-on was installed, and activated unless activation failed
benecaster_manager_addon_install_failed Fires when an install was refused or failed; nothing was installed or removed
benecaster_manager_addon_before_update Fires before an installed add-on’s update is downloaded and checked
benecaster_manager_addon_updated Fires when an add-on’s new version is on disk
benecaster_manager_addon_update_failed Fires when an add-on update was refused or did not finish; the old version is still installed

Migration Wizard

Fire as a migration import runs and as migrated subscribers sign up, lapse, or are handled from the migration dashboard.

Hook Description
benecaster_migration_import_started Fires once when an import opens, before the first CSV row is read
benecaster_migration_subscriber_imported Fires once per imported row, after the account, feed token and patron row exist; not for skipped rows
benecaster_migration_transcript_imported Fires once for each transcript the wizard’s optional transcript step brought in from the source feed.
benecaster_migration_import_complete Fires once when an import has finished and its counts and reconciliation report are written
benecaster_migration_subscriber_completed Fires when a migrated subscriber signs up with you
benecaster_migration_subscriber_dropped Fires when a migrated subscriber’s grace period ends without them signing up
benecaster_migration_invite_resent Fires after Resend queues one person’s Migration Welcome again
benecaster_migration_failed_send_retried Fires after Send again puts a failed welcome email back in the queue
benecaster_migration_patron_note_saved Fires after a podcaster saves their note on one migrated person

Fire as tracked /go/ links are clicked, as Link Health checks links and acts on them, and as tracked links follow their Reference Library items or move with an episode. Most fire only where Outlinks is switched on and the licence is current; each page says which.

Hook Description
benecaster_outlinks_click_logged Fires after a click on a tracked link is recorded, bot clicks included
benecaster_outlinks_before_redirect Fires immediately before a visitor is sent on from a tracked link, with the final address
benecaster_outlinks_health_item_action_before Fires before Link Health dismisses, restores, fixes, unlinks or tracks one item
benecaster_outlinks_health_item_action_after Fires after a Link Health action on one item succeeded
benecaster_outlinks_health_check_completed Fires once a Link Health check finishes, with everything it counts as broken
benecaster_outlinks_health_settings_save_before Fires before Link Health’s schedule is saved
benecaster_outlinks_health_settings_save_after Fires after Link Health’s schedule is saved
benecaster_outlinks_health_exclusions_save_before Fires before Link Health’s exclusions are saved
benecaster_outlinks_health_exclusions_save_after Fires after Link Health’s exclusions are saved, with how many items they removed
benecaster_outlinks_redirect_destination_sync_before Fires before a tracked link follows its library item’s new URL
benecaster_outlinks_redirect_destination_sync_after Fires after a tracked link has followed its library item’s new URL
benecaster_outlinks_redirect_detach_before Fires before a tracked link is kept as a standalone link because its library item was deleted
benecaster_outlinks_redirect_detach_after Fires after a tracked link was kept as a standalone link
benecaster_outlinks_redirect_move_copy_before Fires before a moved episode’s tracked link is copied to the new show
benecaster_outlinks_redirect_move_copy_after Fires after a moved episode’s tracked link was copied to the new show

See Also

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