RFC: Headless Webhooks Plugin

[theodesp]

Headless WordPress Webhooks RFC

Title: Webhooks for Headless WordPress
Author: Theo Despoudis
Status: Draft
Created: April 29, 2025
Last Updated: April 29, 2025

Introduction

This RFC proposes a standardized approach to implementing webhooks in WordPress, specifically designed to enhance headless WordPress architectures.

Problem Statement

Headless WordPress implementations currently lack a standardized, core-supported webhook system. This results in:

• Frontend applications being unable to receive real-time notifications of content changes
• Developers implementing various custom solutions or third-party plugins with different approaches
• Inconsistent experiences across headless WordPress implementations
• Performance challenges when relying on polling APIs instead of event-driven architectures
• Difficulty integrating with external services and middleware

Goals

This RFC aims to:

• Define a standardized webhook system for WordPress that integrates with the core WordPress event system
• Establish clear patterns for webhook registration, delivery, security, and retries
• Maintain backward compatibility with existing WordPress functionality
• Provide extensibility for developers to define custom webhook events
• Create a solution that works effectively for both traditional and headless WordPress implementations
• Integrate with WP-GraphQL to allow authenticated users to query webhooks and their statuses
• Enable headless frontends to efficiently monitor and respond to webhook events
• Ensure the core webhook system is designed with extensibility to integrate with a future self-hosted server seamlessly

Non-Goals

This RFC does not attempt to:

• Replace existing REST API functionality
• Create a comprehensive messaging or queue system
• Implement server-sent events (SSE) or WebSockets (though these could be complementary approaches)
• Dictate the specific frontend implementation details for consuming webhooks
• Directly compete with existing Webhooks plugins like wp-webhooks
• Include the self-hosted server for advanced scenarios in the initial release (planned for future enhancement)

Proposed Solution

Core Components

1. Webhook registration API: A system for registering webhook endpoints and associating them with specific WordPress events
2. Event dispatcher: A mechanism that triggers webhook delivery when registered events occur
3. Webhook delivery system: A reliable system for delivering webhook payloads to registered endpoints
4. Security model: Authentication and authorization controls for webhook registration and delivery
5. Management Interface: Admin UI components for configuring and monitoring webhooks

Webhook Registration

Webhooks should be registrable via:

• Admin UI: A settings page in the WordPress admin area
• WP-GraphQL API: Endpoints for programmatic webhook registration
• Code: PHP functions for developers to register webhooks in themes/plugins

Management Interface

The admin UI should allow:

• Creating, editing, and deleting webhook registrations
• Viewing webhook delivery history and status
• Manually retrying failed webhook deliveries
• Testing webhook endpoints
• Batching webhook deliveries for performance

Standard Events

The following core WordPress events should trigger webhooks, building on the established hooks found in the Atlas Webhooks implementation:

Content Events

• wp_insert_post
• post_updated
• deleted_post
• trashed_post
• draft_to_publish
• publish_post
• comment_post
• edit_comment
• deleted_comment
• trashed_comment
• add_attachment
• edited_terms

User Events

• user_register
• profile_update
• delete_user
• wp_login

System Events

• activated_plugin
• deactivated_plugin
• switch_theme
• update_option

Payload Structure

All webhook payloads should follow a consistent structure:

{
  "event": "post_updated",
  "timestamp": "2025-04-29T14:30:45Z",
  "webhook_id": 123,
  "webhook_name": "content_updated",
  "site_url": "https://example.com",
  "data": {
    "post": {
      "id": 123,
      "type": "post",
      "status": "publish",
      "title": "Post Title",
      "slug": "post-slug",
      "link": "https://example.com/post-slug",
      "modified": "2025-04-29T14:30:40Z",
      "content": "Post content (optional, configurable)",
      "excerpt": "Post excerpt (optional, configurable)",
      "meta": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    "user": {
      "id": 1,
      "name": "Admin User"
    },
    "additional_context": {
      "referer": "edit page"
    }
  },
  "delivery": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attempt": 1,
    "request_type": "POST"
  }
}

Extensibility

The webhook system should be extensible by:

• Allowing plugins to register custom events

• Providing filters to modify webhook payloads

• Supporting custom authentication mechanisms

• Enabling webhook middleware for transformations

Next Steps

After community feedback on this RFC:

• Create a proof-of-concept implementation

• Document the API for developers

• Build example integrations with popular frontend frameworks (Next.js, Gatsby, Nuxt)

Reference Abstractions

Webhook Registration API

interface WebhookRepository {
    public function register(Webhook $webhook): string;
    public function update(string $id, Webhook $webhook): bool;
    public function delete(string $id): bool;
    public function get(string $id): ?Webhook;
    public function list(array $filters = []): array;
}

Event Dispatcher

interface EventDispatcher {
    public function dispatch(Event $event): void;
}

Webhook Delivery System

interface Delivery {
    public function deliver(DeliveryRequest $request): DeliveryResult;
}

Scheduler Abstraction

interface Scheduler {
    public function schedule(DeliveryRequest $request, ?int $time = null): bool;
    public function cancel(string $job_id): bool;
}

[colinmurphy]

@theodesp

I read the RFC and it looks great 🚀 🚀 🚀