feat: webhooks plugin core registration api #193

theodesp · 2025-05-15T15:35:08Z

Description

This PR introduces the core Webhooks Registration API for WPGraphQL Headless Webhooks. It provides the WebhookRegistry singleton class responsible for managing webhook types and webhook instances as a custom post type (graphql_webhook). The API includes functions to register webhook types (register_webhook_type), create webhook instances (create_webhook), and retrieve registered webhook types (get_webhook_type, get_webhook_types).

Related Issue

#164

Dependant PRs

None at this time.

Type of Change

✅ Bug fix (non-breaking change which fixes an issue)
✨ New feature (non-breaking change which adds functionality)
💥 Breaking change (fix or feature that would cause existing functionality to change)
🧹 Code refactoring (no functional changes)
📄 Example update (no functional changes)
📝 Documentation update
🔍 Performance improvement
🧪 Test update

How Has This Been Tested?

Manual testing registering webhook types and creating webhook posts via the API functions.
Verified webhook types are registered correctly on the graphql_register_webhooks hook.
Confirmed webhook posts are created with correct meta data and post type.
Tested retrieval functions return expected webhook type data.
Confirmed no errors or warnings during plugin initialization and webhook registration.

Screenshots

Not applicable (backend API functionality).

Checklist

I have read the CONTRIBUTING document
My code follows the project's coding standards
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation (if applicable)
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works (if applicable)
Any dependent changes have been highlighted, merged or published

#Testing snippet

Use this snippet to test the code:

// Make sure this runs early, e.g., in a plugin's main file or functions.php

// 1. Register multiple webhook types with unique identifiers.
register_webhook_type( 'custom_webhook_type_1', [
    'label'       => 'Custom Webhook Type 1',
    'description' => 'Triggered on event type 1.',
    'config'      => [
        'url'    => 'https://example.com/webhook-endpoint-1',
        'method' => 'POST',
    ],
] );

register_webhook_type( 'custom_webhook_type_2', [
    'label'       => 'Custom Webhook Type 2',
    'description' => 'Triggered on event type 2.',
    'config'      => [
        'url'    => 'https://example.com/webhook-endpoint-2',
        'method' => 'POST',
    ],
] );

// 2. Initialize the WebhookRegistry (usually done by the plugin automatically).
// \WPGraphQL\Webhooks\WebhookRegistry::init(); // Uncomment if needed.

// 3. Create new webhook instances with unique names.
add_action( 'admin_init', function() {
    $post_id_1 = create_webhook(
        'custom_webhook_type_1',
        'Webhook Instance for Type 1',
        [
            'url'    => 'https://example.com/receive-webhook-1',
            'secret' => 'secretkey1',
        ]
    );

    if ( is_wp_error( $post_id_1 ) ) {
        error_log( 'Webhook creation error (Type 1): ' . $post_id_1->get_error_message() );
    } else {
        error_log( 'Webhook created with ID (Type 1): ' . $post_id_1 );
    }

    $post_id_2 = create_webhook(
        'custom_webhook_type_2',
        'Webhook Instance for Type 2',
        [
            'url'    => 'https://example.com/receive-webhook-2',
            'secret' => 'secretkey2',
        ]
    );

    if ( is_wp_error( $post_id_2 ) ) {
        error_log( 'Webhook creation error (Type 2): ' . $post_id_2->get_error_message() );
    } else {
        error_log( 'Webhook created with ID (Type 2): ' . $post_id_2 );
    }
} );

// 4. Display all registered webhook types in admin notices.
add_action( 'admin_notices', function() {
    $webhook_types = get_webhook_types();

    if ( empty( $webhook_types ) ) {
        echo '<div class="notice notice-warning"><p>No webhook types registered.</p></div>';
        return;
    }

    echo '<div class="notice notice-success"><p><strong>Registered Webhook Types:</strong></p><ul>';
    foreach ( $webhook_types as $type => $args ) {
        echo '<li><strong>' . esc_html( $type ) . '</strong>: ' . esc_html( $args['label'] ) . ' - ' . esc_html( $args['description'] ) . '</li>';
    }
    echo '</ul></div>';
} );

plugins/wp-graphql-headless-webhooks/src/WebhookRegistry.php

plugins/wp-graphql-headless-webhooks/access-functions.php

colinmurphy

@theodesp

LGTM 🚀 🚀 🚀

We probably should consider examples too maybe on how to use those hooks.

colinmurphy · 2025-05-15T18:11:38Z

@theodesp

One small thing is I did try and test the snippet in your PR and I got the following error:

[15-May-2025 18:07:56 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function register_webhook_type() in /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-content/themes/twentytwentyfive/functions.php:16
Stack trace:
#0 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-settings.php(695): include()
#1 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-config.php(124): require_once('/Users/colin.mu...')
#2 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-load.php(50): require_once('/Users/colin.mu...')
#3 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-blog-header.php(13): require_once('/Users/colin.mu...')
#4 /Users/colin.murphy/Sites/local/single-test-site/app/public/index.php(17): require('/Users/colin.mu...')
#5 {main}
  thrown in /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-content/themes/twentytwentyfive/functions.php on line 16

Not sure if I was missing anything but the plugin was installed (symlinked from this PR)

theodesp · 2025-05-16T13:01:50Z

@theodesp

One small thing is I did try and test the snippet in your PR and I got the following error:

[15-May-2025 18:07:56 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function register_webhook_type() in /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-content/themes/twentytwentyfive/functions.php:16
Stack trace:
#0 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-settings.php(695): include()
#1 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-config.php(124): require_once('/Users/colin.mu...')
#2 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-load.php(50): require_once('/Users/colin.mu...')
#3 /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-blog-header.php(13): require_once('/Users/colin.mu...')
#4 /Users/colin.murphy/Sites/local/single-test-site/app/public/index.php(17): require('/Users/colin.mu...')
#5 {main}
  thrown in /Users/colin.murphy/Sites/local/single-test-site/app/public/wp-content/themes/twentytwentyfive/functions.php on line 16

Not sure if I was missing anything but the plugin was installed (symlinked from this PR)

@colinmurphy that is strange as I copied those to the same location and does not have any issues

can you try using the https://wordpress.org/plugins/code-snippets/ plugin

whoami-pwd · 2025-05-19T14:49:50Z

plugins/wp-graphql-headless-webhooks/src/Autoloader.php

+ *
+ * @internal
+ */
+class Autoloader {


That would be great for the team to discuss and find the common solution/way for the autoloading for our new plugins. And use unified for all new plugins.

whoami-pwd · 2025-05-19T14:53:04Z

plugins/wp-graphql-headless-webhooks/src/WebhookRegistry.php

+	/**
+	 * Register the webhook CPT
+	 */
+	public function register_webhook_cpt(): void {


Maybe there is a benefit to have Post registration functionality separately, in a separate class?

Also can we discuss what benefits we have when utilizing it as a Post Type vs Options/Settings?

Thanks @whoami-pwd . I will refactor. After discussion with @josephfusco I think using CPT provides several benefics over settings:

CPTs provide built-in admin UI, revision history, meta fields per webhook, and native REST/GraphQL integration. We can create multiple hooks as a separate database entry rather than bloating a single serialized options array. The CPT structure also enables more granular permissions as well. So Im not sure how scalable the Options/Settings variant will be in that case.

colinmurphy

@theodesp LGTM 🚀 🚀 🚀

The merge-base changed after approval.

theodesp · 2025-05-21T09:42:00Z

plugins/wp-graphql-headless-webhooks/src/PostTypes/WebhookPostType.php

@@ -0,0 +1,64 @@
+<?php


Separated this in a new class

theodesp added 2 commits May 15, 2025 11:47

feat: add autoloader

f386b19

feat: core webhooks registration API

a6e817a

theodesp requested a review from a team as a code owner May 15, 2025 15:35

theodesp commented May 15, 2025

View reviewed changes

plugins/wp-graphql-headless-webhooks/src/WebhookRegistry.php Show resolved Hide resolved

theodesp commented May 15, 2025

View reviewed changes

plugins/wp-graphql-headless-webhooks/access-functions.php Outdated Show resolved Hide resolved

colinmurphy previously approved these changes May 15, 2025

View reviewed changes

lint: include stricter phpcs, psalm, phpstan rules

1b76a1d

theodesp dismissed colinmurphy’s stale review via 1b76a1d May 16, 2025 12:00

lint: passing phpstan checks

6d0356c

whoami-pwd reviewed May 19, 2025

View reviewed changes

theodesp changed the title ~~Feat webhooks plugin core registration api~~ feat: webhooks plugin core registration api May 19, 2025

colinmurphy previously approved these changes May 19, 2025

View reviewed changes

theodesp added 2 commits May 21, 2025 10:01

Merge branch 'main' into feat-webhooks-plugin-core-registration-api

bea81da

chore: refactor WebhookRegistry

deb2ad3

theodesp requested review from whoami-pwd and colinmurphy May 21, 2025 09:41

theodesp commented May 21, 2025

View reviewed changes

plugins/wp-graphql-headless-webhooks/src/PostTypes/WebhookPostType.php

@@ -0,0 +1,64 @@

<?php

Copy link

Member Author

theodesp May 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Separated this in a new class

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: webhooks plugin core registration api #193

feat: webhooks plugin core registration api #193

theodesp commented May 15, 2025 •

edited

Loading

colinmurphy left a comment

colinmurphy commented May 15, 2025

theodesp commented May 16, 2025

whoami-pwd May 19, 2025

whoami-pwd May 19, 2025

theodesp May 21, 2025

colinmurphy left a comment

theodesp May 21, 2025

feat: webhooks plugin core registration api #193

Are you sure you want to change the base?

feat: webhooks plugin core registration api #193

Conversation

theodesp commented May 15, 2025 • edited Loading

Description

Related Issue

Dependant PRs

Type of Change

How Has This Been Tested?

Screenshots

Checklist

colinmurphy left a comment

Choose a reason for hiding this comment

colinmurphy commented May 15, 2025

theodesp commented May 16, 2025

whoami-pwd May 19, 2025

Choose a reason for hiding this comment

whoami-pwd May 19, 2025

Choose a reason for hiding this comment

theodesp May 21, 2025

Choose a reason for hiding this comment

colinmurphy left a comment

Choose a reason for hiding this comment

theodesp May 21, 2025

Choose a reason for hiding this comment

theodesp commented May 15, 2025 •

edited

Loading