Skip to main content

benecaster_token_revoked

Action Premium

Fires when a subscriber’s token is revoked one at a time — a cancellation reported by the membership plugin, a podcaster removing someone, a manual grant reaching its end date, a promotion grace window running out, or an account being deleted. After this hook fires, the token is immediately inactive and the subscriber’s feed will return empty on its next poll.

$reason says which it was. It is the value just recorded in the token’s revocation_reason, one of the RevocationReasons values: bridge_cancellation (the subscriber cancelled or lapsed in their membership plugin), admin_revoked (the podcaster removed them), manual_grant_expired, promote_grace_expired, account_deleted, or an add-on’s own reason. It is '' when the revoking code passed none. The token row looks the same for all of them, so tell a cancellation from a removal by $reason, never by reading the row. Declare 10, 4 to receive it; a callback registered for three arguments keeps working without it. To tell a follower from a paying subscriber, pass $token_id to benecaster_get_token_type() and branch on its base.

Token revocation is distinct from subscription cancellation. Revoking a token removes the subscriber’s feed access without touching their membership plugin subscription — the subscription continues to exist in your membership plugin; Benecaster simply stops serving the feed for that token. Use this hook to audit or log access revocations that occur outside the normal subscription lifecycle. For revocations initiated specifically by an admin through the subscriber detail panel, see benecaster_subscriber_access_revoked.

Not every revocation fires it, and it fires once per revocation. The day-30 license cutoff and the one-off sweep of old lapses revoke without it, so nothing that sends an email reacts to them. They fire benecaster_token_quietly_revoked instead. An already-revoked row is left as it is, and a reason that replaces another on it fires the quiet action too.

Parameters

Name Type Default Description
$token_id int — ID of the revoked token record
$user_id int — WordPress user ID
$show_id int — ID of the show
$reason string — Why the token was revoked — a RevocationReasons value such as `bridge_cancellation`, `admin_revoked` or `manual_grant_expired`; `''` when none was given. Declare `10, 4` to receive it.

Examples

Tag a cancellation and a removal differently

add_action( 'benecaster_token_revoked', function ( int $token_id, int $user_id, int $show_id, string $reason ): void {
    if ( \Benecaster\Token\RevocationReasons::ADMIN_REVOKED === $reason ) {
        my_crm_tag( $user_id, 'removed-by-podcaster' );
    } elseif ( \Benecaster\Token\RevocationReasons::BRIDGE_CANCELLATION === $reason ) {
        my_crm_tag( $user_id, 'cancelled' );
    }
}, 10, 4 );

Insert revocation to audit log

add_action( 'benecaster_token_revoked', function (
    int $token_id,
    int $user_id,
    int $show_id,
    string $reason
) {
    global $wpdb;

    $wpdb->insert(
        $wpdb->prefix . 'my_security_audit_log',
        [
            'event'      => 'token_revoked',
            'token_id'   => $token_id,
            'user_id'    => $user_id,
            'show_id'    => $show_id,
            'reason'     => $reason,
            'revoked_at' => current_time( 'mysql' ),
            'revoked_by' => get_current_user_id(),
        ],
        [ '%s', '%d', '%d', '%d', '%s', '%s', '%d' ]
    );
}, 10, 4 );

Notes

Use benecaster_subscription_cancelled to respond to the normal subscription cancellation lifecycle — token revocation is not the standard cancellation path.

Not every revocation fires this hook. The license grace cutoff and the sweep that catches memberships found to have lapsed revoke many tokens in one step and fire nothing. A listener that must see those reads revocation_reason from benecaster_get_subscriber_data() the next time it deals with the person.

Related Recipes

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