Skip to main content

Fire add-on side effects the moment an OAuth site-linking exchange succeeds for a specific show

Premium Intermediate

Connecting a show to a Benecaster account is a one-time moment, and a good one for an add-on to do its own first-run work: create whatever it needs, start an initial sync, record that the connection happened.

benecaster_site_connected fires once, the instant that connection succeeds, and passes the details that came back with it — when the grant was made, which licence and plan it belongs to, and the show’s identifier.

The connection token is a credential. Do not send it anywhere. It is included so that local code can use it, not so it can be forwarded — relaying it to a third-party service hands that service the show’s access.

Do Not Rely On This Alone For First-Run Setup

This fires once, at the moment of connection — and an add-on installed afterwards has already missed it. That is the common case, not an edge case: most podcasters connect their show first and discover add-ons later. An add-on that only does its first-run work here simply never runs it on those sites, and the failure is silent.

Treat the hook as an optimisation rather than the mechanism. Do your setup wherever you normally would — on activation, or on first boot — and check whether the show is already connected. Then use this hook for the case your check could not cover: an add-on that was installed before the connection existed, and is waiting for it. Between the two, every ordering is handled.

Code

<?php
add_action( 'benecaster_site_connected', function ( array $data ): void {
    $show_uuid = (string) ( $data['show_uuid'] ?? '' );

    // Kick off a first-time sync as soon as this show is licensed.
    wp_schedule_single_event( time() + 10, 'my_addon_initial_sync', [ $show_uuid ] );

    // Log the connect event without persisting the token itself.
    my_addon_audit_log( sprintf(
        'Benecaster connected: show_uuid=%s license_id=%d plan=%s',
        $show_uuid,
        (int) ( $data['license_id'] ?? 0 ),
        (string) ( $data['plan'] ?? '' )
    ) );
} );

View on GitHub →

Hooks Used

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

Powered by