Skip to main content

Register a custom admin notice health check that runs once per admin session

Premium Advanced

Some problems an add-on can detect are invisible until something breaks — an API key that stopped working, a setting left half-configured, a dependency that went away. A health check lets your add-on watch for that condition and raise a notice in the admin when it finds it.

You write one small class that knows how to answer a single question, and Benecaster runs it for you once per admin session. The same method both raises the notice when the condition is present and clears it when the condition resolves, so the podcaster never has to dismiss a warning about something that already fixed itself.

When to Use This

Use it for conditions worth interrupting someone about, and that they can act on. A check that fires constantly, or that reports something the podcaster cannot change, trains people to ignore the notice area entirely.

The One Rule

Running the check twice on the same state must produce the same result. Benecaster runs it repeatedly, so raising and clearing have to be safe to repeat — otherwise the notice flickers on and off as the podcaster moves around the admin.

A check that throws is contained and will not take down the admin screen or stop the other checks from running.

Code

<?php
use Benecaster\Notices\HealthChecks\HealthCheck;
use Benecaster\Notices\NoticeManager;

class StripeWebhookHealthCheck implements HealthCheck {

    private const NOTICE_ID = 'myaddon_health_stripe_webhook';

    public function __construct( private readonly NoticeManager $notices ) {}

    public function evaluate(): void {
        $last_seen = (int) get_option( 'myaddon_stripe_webhook_last_seen', 0 );

        // No webhook event in the last 24 hours and the gateway is connected → warn.
        if ( $last_seen > 0 && ( time() - $last_seen ) < DAY_IN_SECONDS ) {
            $this->notices->delete( self::NOTICE_ID );
            return;
        }

        $this->notices->publish( [
            'notice_id'    => self::NOTICE_ID,
            'type'         => 'warning',
            'display_mode' => 'both',
            'source'       => 'local',
            'title'        => __( 'Stripe webhooks have stopped', 'my-addon' ),
            'message'      => __( 'No Stripe webhook events received in the last 24 hours — verify your webhook endpoint.', 'my-addon' ),
            'action_url'   => admin_url( 'admin.php?page=myaddon-stripe' ),
            'action_label' => __( 'Open Stripe settings', 'my-addon' ),
            'dismissible'  => true,
        ] );
    }
}

add_action( 'benecaster_boot', function ( \Benecaster\Container $container ): void {
    $notices = $container->make( NoticeManager::class );
    $notices->add_health_check( new StripeWebhookHealthCheck( $notices ) );
} );

View on GitHub →

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

Powered by