claude-plugin-wordpress-manager 2.1.0 → 2.2.0

package/skills/wp-webhooks/references/integration-recipes.md

@@ -0,0 +1,176 @@
+# Integration Recipes
+
+## Overview
+
+Common webhook integration patterns for connecting WordPress to external services. Each recipe shows the webhook configuration and expected behavior.
+
+## Zapier Integration
+
+**Setup:**
+1. Create a Zap with "Webhooks by Zapier" as trigger (Catch Hook)
+2. Copy the Zapier webhook URL
+3. Create webhook in WordPress:
+   ```
+   Tool: wc_create_webhook (for WooCommerce events)
+   name: "Zapier - New Orders"
+   topic: "order.created"
+   delivery_url: "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
+   secret: "zapier-secret"
+   ```
+4. Test by creating a test order
+5. Configure Zapier actions (email, Slack, Google Sheets, etc.)
+
+**Common Zaps:**
+| Trigger | Action | Use Case |
+|---------|--------|----------|
+| New order | Send email | Order confirmation to team |
+| New order | Add row to Google Sheet | Order tracking spreadsheet |
+| New product | Post to Slack | Team notification |
+| New customer | Add to Mailchimp | Email list growth |
+
+## Make (Integromat) Integration
+
+**Setup:**
+1. Create a scenario with "Webhooks" module (Custom webhook)
+2. Copy the Make webhook URL
+3. Create webhook:
+   ```
+   delivery_url: "https://hook.eu1.make.com/abc123def456"
+   ```
+4. Run the scenario once to register the webhook structure
+5. Map fields and configure subsequent modules
+
+**Common Scenarios:**
+- Order placed → Create invoice in QuickBooks
+- Product updated → Sync to external catalog
+- Customer created → Add to CRM (HubSpot, Pipedrive)
+
+## n8n Integration
+
+**Setup (self-hosted n8n):**
+1. Create a workflow with "Webhook" trigger node
+2. Set to POST method, configure path
+3. Copy the production webhook URL
+4. Create webhook:
+   ```
+   delivery_url: "https://n8n.example.com/webhook/wordpress-events"
+   ```
+
+**Common Workflows:**
+- Content published → SEO check → Notify team
+- Order → Inventory check → Fulfillment API
+- Customer feedback → Sentiment analysis → Support ticket
+
+## Slack Notifications
+
+**Setup:**
+1. Create a Slack Incoming Webhook in Slack App settings
+2. Use the mu-plugin approach (WordPress core webhooks) with custom formatting:
+
+```php
+add_action('transition_post_status', function($new, $old, $post) {
+    if ($new === 'publish' && $old !== 'publish') {
+        $slack_url = defined('SLACK_WEBHOOK_URL') ? SLACK_WEBHOOK_URL : '';
+        if (!$slack_url) return;
+
+        wp_remote_post($slack_url, [
+            'headers' => ['Content-Type' => 'application/json'],
+            'body'    => wp_json_encode([
+                'text' => sprintf(
+                    "New %s published: *%s*\n<%s|Read it here>",
+                    $post->post_type,
+                    $post->post_title,
+                    get_permalink($post)
+                ),
+            ]),
+        ]);
+    }
+}, 10, 3);
+```
+
+## Email Service Integration
+
+### Mailchimp / SendGrid
+
+**Trigger:** New subscriber or customer event
+**Method:** WooCommerce webhook → Zapier/Make → Mailchimp API
+
+Or direct with mu-plugin:
+```php
+add_action('user_register', function($user_id) {
+    $user = get_userdata($user_id);
+    // POST to Mailchimp API to add subscriber
+    wp_remote_post('https://usX.api.mailchimp.com/3.0/lists/LIST_ID/members', [
+        'headers' => [
+            'Authorization' => 'Bearer ' . MAILCHIMP_API_KEY,
+            'Content-Type'  => 'application/json',
+        ],
+        'body' => wp_json_encode([
+            'email_address' => $user->user_email,
+            'status'        => 'subscribed',
+        ]),
+    ]);
+});
+```
+
+## CDN Purge
+
+### Cloudflare
+
+**Trigger:** Content updated
+**Method:** mu-plugin that purges Cloudflare cache on publish:
+
+```php
+add_action('transition_post_status', function($new, $old, $post) {
+    if ($new === 'publish') {
+        wp_remote_post(
+            'https://api.cloudflare.com/client/v4/zones/' . CF_ZONE_ID . '/purge_cache',
+            [
+                'headers' => [
+                    'Authorization' => 'Bearer ' . CF_API_TOKEN,
+                    'Content-Type'  => 'application/json',
+                ],
+                'body' => wp_json_encode([
+                    'files' => [get_permalink($post)],
+                ]),
+            ]
+        );
+    }
+}, 10, 3);
+```
+
+## Search Index Update
+
+### Algolia / Meilisearch
+
+**Trigger:** Content published or updated
+**Method:** WooCommerce webhook or mu-plugin → search API
+
+```php
+add_action('save_post', function($post_id, $post) {
+    if ($post->post_status !== 'publish') return;
+
+    wp_remote_post(ALGOLIA_API_URL . '/indexes/posts', [
+        'headers' => [
+            'X-Algolia-API-Key'        => ALGOLIA_ADMIN_KEY,
+            'X-Algolia-Application-Id' => ALGOLIA_APP_ID,
+            'Content-Type'             => 'application/json',
+        ],
+        'body' => wp_json_encode([
+            'objectID' => $post_id,
+            'title'    => $post->post_title,
+            'content'  => wp_strip_all_tags($post->post_content),
+            'url'      => get_permalink($post),
+        ]),
+    ]);
+}, 10, 2);
+```
+
+## Best Practices
+
+- Always use HTTPS for delivery URLs
+- Set a webhook secret and verify signatures on the receiving end
+- Keep webhook timeout under 5 seconds to avoid blocking WordPress
+- Use async processing on the receiving end for heavy operations
+- Monitor webhook delivery logs for failures
+- Group related events when possible to reduce webhook volume

package/skills/wp-webhooks/references/payload-formats.md

@@ -0,0 +1,134 @@
+# Webhook Payload Formats
+
+## Standard WordPress Webhook Payload
+
+When using the mu-plugin approach, payloads follow this structure:
+
+```json
+{
+  "event": "post.published",
+  "timestamp": "2026-02-28T14:30:00+00:00",
+  "site_url": "https://example.com",
+  "data": {
+    "id": 123,
+    "title": "Post Title",
+    "slug": "post-title",
+    "type": "post",
+    "url": "https://example.com/post-title/"
+  }
+}
+```
+
+### Event Types
+
+| Event | Data Fields |
+|-------|-------------|
+| `post.published` | id, title, slug, type, url |
+| `post.updated` | id, title, slug, type, url |
+| `term.updated` | id, name, slug, taxonomy |
+| `user.created` | id, username, email, role |
+| `menu.updated` | menu_id |
+
+## WooCommerce Webhook Payloads
+
+WooCommerce sends the full resource object as the payload.
+
+### Order Created Payload (truncated)
+
+```json
+{
+  "id": 456,
+  "status": "processing",
+  "currency": "EUR",
+  "total": "29.99",
+  "customer_id": 12,
+  "billing": {
+    "first_name": "Mario",
+    "last_name": "Rossi",
+    "email": "mario@example.com",
+    "phone": "+39 123 456 7890",
+    "address_1": "Via Roma 1",
+    "city": "Palermo",
+    "state": "PA",
+    "postcode": "90100",
+    "country": "IT"
+  },
+  "line_items": [
+    {
+      "id": 1,
+      "name": "Cactus Water - Dolce",
+      "product_id": 78,
+      "quantity": 6,
+      "total": "29.99"
+    }
+  ],
+  "date_created": "2026-02-28T14:30:00",
+  "payment_method": "stripe",
+  "payment_method_title": "Credit Card"
+}
+```
+
+### Product Updated Payload (truncated)
+
+```json
+{
+  "id": 78,
+  "name": "Cactus Water - Dolce",
+  "slug": "cactus-water-dolce",
+  "type": "simple",
+  "status": "publish",
+  "price": "4.99",
+  "regular_price": "5.99",
+  "sale_price": "4.99",
+  "stock_quantity": 150,
+  "stock_status": "instock",
+  "categories": [
+    { "id": 3, "name": "Beverages", "slug": "beverages" }
+  ]
+}
+```
+
+## Custom Payload Formatting
+
+### Minimal Payload (reduce bandwidth)
+
+If the receiving service only needs specific fields, format a custom payload in the mu-plugin:
+
+```php
+send_webhook('order.created', [
+    'order_id' => $order->get_id(),
+    'total'    => $order->get_total(),
+    'email'    => $order->get_billing_email(),
+    'items'    => count($order->get_items()),
+]);
+```
+
+### Enriched Payload (add computed fields)
+
+```php
+send_webhook('post.published', [
+    'id'         => $post->ID,
+    'title'      => $post->post_title,
+    'url'        => get_permalink($post),
+    'word_count' => str_word_count(wp_strip_all_tags($post->post_content)),
+    'categories' => wp_get_post_categories($post->ID, ['fields' => 'names']),
+    'author'     => get_the_author_meta('display_name', $post->post_author),
+]);
+```
+
+## Content-Type Headers
+
+| Format | Content-Type | When to Use |
+|--------|-------------|-------------|
+| JSON | `application/json` | Default, most integrations |
+| Form-encoded | `application/x-www-form-urlencoded` | Legacy systems |
+| XML | `application/xml` | SOAP integrations |
+
+WooCommerce always sends `application/json`. The mu-plugin approach defaults to JSON but can be customized.
+
+## Payload Size Considerations
+
+- **WooCommerce**: Full resource payloads can be large (5-50 KB for orders with many items)
+- **Custom payloads**: Keep under 1 MB for reliability
+- **Truncation strategy**: For large content fields, send an ID + URL instead of the full body
+- **Batch events**: If multiple events fire in quick succession, consider debouncing on the receiving end

package/skills/wp-webhooks/references/webhook-security.md

@@ -0,0 +1,147 @@
+# Webhook Security
+
+## Overview
+
+Webhook security ensures that only legitimate notifications are processed by the receiving endpoint. Without verification, an attacker could send fake payloads to trigger unauthorized actions.
+
+## Shared Secret Authentication (HMAC-SHA256)
+
+The standard approach: sender and receiver share a secret key. The sender computes an HMAC hash of the payload and includes it in a header. The receiver recomputes the hash and compares.
+
+### Sending (WordPress side)
+
+```php
+$payload   = wp_json_encode($data);
+$secret    = WEBHOOK_SECRET;
+$signature = hash_hmac('sha256', $payload, $secret);
+
+wp_remote_post($url, [
+    'headers' => [
+        'Content-Type'              => 'application/json',
+        'X-WP-Webhook-Signature'    => $signature,
+    ],
+    'body' => $payload,
+]);
+```
+
+### Receiving (endpoint side)
+
+```javascript
+const crypto = require('crypto');
+
+function verifyWebhookSignature(rawBody, signature, secret) {
+  const expected = crypto
+    .createHmac('sha256', secret)
+    .update(rawBody, 'utf8')
+    .digest('hex');
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  );
+}
+
+// In your webhook handler:
+app.post('/webhook', (req, res) => {
+  const signature = req.headers['x-wp-webhook-signature'];
+  if (!verifyWebhookSignature(req.rawBody, signature, SECRET)) {
+    return res.status(401).json({ error: 'Invalid signature' });
+  }
+  // Process the webhook...
+  res.status(200).json({ received: true });
+});
+```
+
+## WooCommerce Signature Verification
+
+WooCommerce uses base64-encoded HMAC-SHA256 in the `X-WC-Webhook-Signature` header:
+
+```javascript
+function verifyWooCommerceWebhook(rawBody, signature, secret) {
+  const expected = crypto
+    .createHmac('sha256', secret)
+    .update(rawBody, 'utf8')
+    .digest('base64');
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  );
+}
+```
+
+**Important:** Always use `crypto.timingSafeEqual()` to prevent timing attacks.
+
+## HTTPS Enforcement
+
+- **Always use HTTPS** for delivery URLs — never HTTP in production
+- WooCommerce webhooks require HTTPS by default (configurable)
+- Self-signed certificates will cause delivery failures
+- Use Let's Encrypt for free, auto-renewing SSL
+
+## IP Allowlisting
+
+If the receiving endpoint supports it, restrict incoming webhooks to known IPs:
+
+| Source | IP Ranges |
+|--------|-----------|
+| Your WordPress host | Check with your hosting provider |
+| Zapier | Published at zapier.com/help/account/data-management/ip-addresses |
+| Make | Published in Make documentation |
+
+**Note:** IP allowlisting is a defense-in-depth measure, not a replacement for signature verification.
+
+## Rate Limiting
+
+### Sender Side (WordPress)
+- Debounce rapid-fire events (e.g., bulk post updates)
+- Use `wp_schedule_single_event()` for non-urgent webhooks
+- Limit to 1 webhook per resource per 5 seconds
+
+### Receiver Side
+- Accept webhooks immediately (200 OK) and process asynchronously
+- Queue incoming webhooks for processing
+- Reject if rate exceeds threshold (429 Too Many Requests)
+
+## Timeout Configuration
+
+- **WordPress default timeout**: 5 seconds (`wp_remote_post` timeout parameter)
+- **WooCommerce default**: 5 seconds
+- **Recommendation**: Keep timeouts at 5 seconds or less
+- If the receiver needs more time, respond 200 immediately and process in background
+
+## Retry Behavior
+
+### WooCommerce Built-in Retries
+- Retries up to 5 times on failure
+- Exponential backoff between retries
+- After 5 failures: webhook set to `disabled`
+- Re-enable manually via `wc_update_webhook` with `status: "active"`
+
+### Custom Retry (mu-plugin)
+```php
+function send_webhook_with_retry($url, $payload, $max_retries = 3) {
+    for ($i = 0; $i < $max_retries; $i++) {
+        $response = wp_remote_post($url, [
+            'timeout' => 5,
+            'headers' => ['Content-Type' => 'application/json'],
+            'body'    => wp_json_encode($payload),
+        ]);
+        if (!is_wp_error($response) && wp_remote_retrieve_response_code($response) === 200) {
+            return true;
+        }
+        sleep(pow(2, $i)); // Exponential backoff: 1s, 2s, 4s
+    }
+    error_log("Webhook delivery failed after {$max_retries} retries: {$url}");
+    return false;
+}
+```
+
+## Security Checklist
+
+- [ ] HTTPS enforced on all delivery URLs
+- [ ] Shared secret configured and verified
+- [ ] Signature verification uses timing-safe comparison
+- [ ] Payload validated (expected structure and types)
+- [ ] Rate limiting in place on receiver
+- [ ] Timeout set to 5 seconds or less
+- [ ] Failed webhooks logged for monitoring
+- [ ] Secrets stored securely (environment variables, not code)

package/skills/wp-webhooks/references/woocommerce-webhooks.md

@@ -0,0 +1,129 @@
+# WooCommerce Webhooks
+
+## Overview
+
+WooCommerce provides a built-in webhook system via the `wc/v3/webhooks` REST API. Webhooks send JSON payloads to a delivery URL when specific store events occur. This is the preferred approach for WooCommerce event notifications — no custom code needed.
+
+## MCP Tools
+
+The WP REST Bridge provides 4 tools for managing WooCommerce webhooks:
+
+| Tool | Method | Endpoint | Purpose |
+|------|--------|----------|---------|
+| `wc_list_webhooks` | GET | `webhooks` | List all webhooks, optionally filter by status |
+| `wc_create_webhook` | POST | `webhooks` | Create a new webhook with topic and delivery URL |
+| `wc_update_webhook` | PUT | `webhooks/{id}` | Update webhook status, URL, or topic |
+| `wc_delete_webhook` | DELETE | `webhooks/{id}` | Delete a webhook (safety hook requires confirmation) |
+
+## Available Topics
+
+### Order Topics
+| Topic | Trigger |
+|-------|---------|
+| `order.created` | New order placed |
+| `order.updated` | Order details changed |
+| `order.deleted` | Order deleted |
+| `order.restored` | Order restored from trash |
+
+### Product Topics
+| Topic | Trigger |
+|-------|---------|
+| `product.created` | New product published |
+| `product.updated` | Product details changed |
+| `product.deleted` | Product deleted |
+| `product.restored` | Product restored from trash |
+
+### Customer Topics
+| Topic | Trigger |
+|-------|---------|
+| `customer.created` | New customer registered |
+| `customer.updated` | Customer profile changed |
+| `customer.deleted` | Customer deleted |
+
+### Coupon Topics
+| Topic | Trigger |
+|-------|---------|
+| `coupon.created` | New coupon created |
+| `coupon.updated` | Coupon details changed |
+| `coupon.deleted` | Coupon deleted |
+
+### Action Topic
+| Topic | Trigger |
+|-------|---------|
+| `action.woocommerce_*` | Any WooCommerce action hook |
+
+## Usage Examples
+
+### Create a webhook for new orders
+
+```
+Tool: wc_create_webhook
+Params:
+  name: "New Order Notification"
+  topic: "order.created"
+  delivery_url: "https://hooks.zapier.com/hooks/catch/123/abc"
+  secret: "my-webhook-secret-key"
+  status: "active"
+```
+
+### List active webhooks
+
+```
+Tool: wc_list_webhooks
+Params:
+  status: "active"
+```
+
+### Pause a webhook
+
+```
+Tool: wc_update_webhook
+Params:
+  id: 42
+  status: "paused"
+```
+
+## Webhook Status
+
+| Status | Description |
+|--------|-------------|
+| `active` | Webhook is delivering payloads |
+| `paused` | Webhook exists but is not delivering |
+| `disabled` | Webhook was disabled (usually after delivery failures) |
+
+## Delivery Behavior
+
+- **Timeout**: 5 seconds (configurable via `woocommerce_webhook_deliver_async`)
+- **Retries**: WooCommerce retries failed deliveries up to 5 times with exponential backoff
+- **Failure threshold**: After 5 consecutive failures, webhook is automatically set to `disabled`
+- **Logs**: Delivery logs available in WooCommerce > Status > Logs
+
+## Webhook Headers
+
+WooCommerce sends these headers with every delivery:
+
+```
+X-WC-Webhook-Source: https://your-site.com/
+X-WC-Webhook-Topic: order.created
+X-WC-Webhook-Resource: order
+X-WC-Webhook-Event: created
+X-WC-Webhook-Signature: <HMAC-SHA256 hash>
+X-WC-Webhook-ID: 42
+X-WC-Webhook-Delivery-ID: <uuid>
+```
+
+## Signature Verification
+
+The receiving endpoint should verify the `X-WC-Webhook-Signature` header:
+
+```javascript
+const crypto = require('crypto');
+
+function verifyWebhook(payload, signature, secret) {
+  const hash = crypto
+    .createHmac('sha256', secret)
+    .update(payload, 'utf8')
+    .digest('base64');
+  return hash === signature;
+}
+```