Notifications – WP Webhook Framework

Extensible notification system for webhook events using registry pattern. Notifications are opt-in per webhook.

Overview

Respond to webhook events (success, failure, blocking) with custom handlers like email alerts, Slack messages, or monitoring integrations.

Core Concepts

Notification Handlers

Each handler:

Extends Notification abstract class
Implements get_identifier(): string
Implements init(): void to register hooks
Is opt-in per webhook

Enabling Notifications

add_action( 'wpwf_register_webhooks', function ( Webhook_Registry $registry ): void {
    $post_webhook = new \juvo\WP_Webhook_Framework\Webhooks\Post_Webhook();
    $post_webhook->webhook_url( 'https://api.example.com/posts' )
                 ->notifications( array( 'blocked' ) );

    $registry->register( $post_webhook );
} );

Built-in: `blocked` Email Notification

Sends email when a webhook URL is blocked.

Identifier: 'blocked'
Triggers on: wpwf_webhook_blocked
Recipient: Site admin (admin_email)

Customizing Email

add_filter( 'wpwf_blocked_notification_email', function ( array $email_data, string $url, mixed $response ): array {
    $email_data['recipient'] = 'webhooks@example.com';
    $email_data['subject']   = sprintf( '[URGENT] Webhook Blocked: %s', $url );
    return $email_data;
}, 10, 3 );

Custom Notification Handlers

Creating a Handler

class Slack_Notification extends Notification {

    private string $webhook_url;

    public function __construct( string $webhook_url ) {
        $this->webhook_url = $webhook_url;
    }

    public function get_identifier(): string {
        return 'slack';
    }

    public function init(): void {
        add_action( 'wpwf_webhook_blocked', array( $this, 'send_alert' ), 10, 4 );
    }

    public function send_alert( string $url, array $response, int $max_failures, Webhook $webhook ): void {
        wp_remote_post( $this->webhook_url, array(
            'body'    => wp_json_encode( array(
                'text' => "Webhook '{$webhook->get_name()}' blocked: {$url}",
            ) ),
            'headers' => array( 'Content-Type' => 'application/json' ),
        ) );
    }
}

Registering Handlers

add_action( 'wpwf_register_notifications', function ( Notification_Registry $registry ): void {
    $url = get_option( 'slack_webhook_url' );
    if ( ! empty( $url ) ) {
        $registry->register( new Slack_Notification( $url ) );
    }
} );

Enabling Custom Handlers

add_action( 'wpwf_register_webhooks', function ( Webhook_Registry $registry ): void {
    $webhook = new \juvo\WP_Webhook_Framework\Webhooks\Post_Webhook();
    $webhook->webhook_url( 'https://api.example.com/posts' )
            ->notifications( array( 'blocked', 'slack' ) );

    $registry->register( $webhook );
} );

Notification Registry API

$registry = Service_Provider::get_notification_registry();

$registry->is_registered( 'slack' );           // bool
$registry->get_registered_identifiers();       // array<string>
$registry->get( 'blocked' );                   // Notification|null

Best Practices

Conditional Registration

add_action( 'wpwf_register_notifications', function ( Notification_Registry $registry ): void {
    $api_key = get_option( 'monitoring_api_key' );
    if ( ! empty( $api_key ) ) {
        $registry->register( new Monitoring_Notification( $api_key ) );
    }
} );

Environment-Specific

add_action( 'wpwf_register_webhooks', function ( Webhook_Registry $registry ): void {
    $webhook = new \juvo\WP_Webhook_Framework\Webhooks\Post_Webhook();
    $webhook->webhook_url( 'https://api.example.com/posts' );

    $notifications = array( 'blocked' );
    if ( 'production' === wp_get_environment_type() ) {
        $notifications[] = 'slack';
    }

    $webhook->notifications( $notifications );
    $registry->register( $webhook );
} );

Error Handling

public function send_notification( string $url, mixed $response ): void {
    $result = wp_remote_post( $this->endpoint, array(
        'body'    => $this->build_payload( $url, $response ),
        'timeout' => 5,
    ) );

    if ( is_wp_error( $result ) ) {
        error_log( 'Notification failed: ' . $result->get_error_message() );
    }
}