Skip to main content
skill CX Codex

woocommerce-webhooks — Claude Code skill: webhook verification

Sets up and validates WooCommerce webhooks in Node.js and Python. Handles signature verification and store events like order or product updates.

MIT 213 installs ★ 103 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-code
Open on GitHub

What woocommerce-webhooks does

This skill guides agents through handling WooCommerce store payloads and verifying signatures. It covers computing the SHA-256 HMAC in base64, comparing hashes safely, and reading headers like X-WC-Webhook-Signature.

Code patterns support Express, Next.js App Router, and FastAPI. Signature checks fail immediately if JSON middleware parses the payload before hashing: the handler strictly requires the unparsed raw request body.

For local testing, the skill uses Hookdeck CLI to tunnel requests to port 3000. Set your secret key in WOOCOMMERCE_WEBHOOK_SECRET.

What it helps with

  • verify WooCommerce HMAC SHA-256 signatures with timing-safe checks
  • write webhook endpoints for Express, Next.js App Router, or FastAPI
  • extract event topics like order.created and parse store payloads
  • inspect and test store webhooks locally using Hookdeck CLI

Example prompts for the agent

  • Write an Express webhook endpoint that validates WooCommerce signatures
  • How do I verify X-WC-Webhook-Signature in a Next.js App Router route?
  • Create a FastAPI handler for WooCommerce order.updated events

How to install woocommerce-webhooks

1Skills CLI (Vercel)

npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-code

2Manually: put the files in place

~/.claude/skills/woocommerce-webhooks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/woocommerce-webhooks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about woocommerce-webhooks

How to install woocommerce-webhooks in Claude Code?

Run npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-code. The file will be installed to ~/.claude/skills/woocommerce-webhooks/SKILL.md.

What does woocommerce-webhooks do?

It provides signature verification logic and server handlers for WooCommerce store events, covering orders, products, and customer updates.

Why does WooCommerce signature verification fail?

HMAC calculation requires the unparsed raw request body. If body parser middleware converts the payload to JSON first, the digest calculation will not match.

Source text

SKILL.md · MIT
---
name: woocommerce-webhooks
description: >
  Receive and verify WooCommerce webhooks. Use when setting up WooCommerce webhook
  handlers, debugging signature verification, or handling e-commerce events like
  order.created, order.updated, product.created, or customer.created.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# WooCommerce Webhooks

## When to Use This Skill

- Setting up WooCommerce webhook handlers
- Debugging signature verification failures
- Understanding WooCommerce event types and payloads
- Handling order, product, or customer events
- Integrating with WooCommerce stores

## Essential Code (USE THIS)

### WooCommerce Signature Verification (JavaScript)

```javascript
const crypto = require('crypto');

function verifyWooCommerceWebhook(rawBody, signature, secret) {
  if (!signature || !secret) return false;
  
  const hash = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');
  
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature), 
      Buffer.from(hash)
    );
  } catch {
    return false;
  }
}
```

### Express Webhook Handler

```javascript
const express = require('express');
const app = express();

// CRITICAL: Use raw body for signature verification
app.use('/webhooks/woocommerce', express.raw({ type: 'application/json' }));

app.post('/webhooks/woocommerce', (req, res) => {
  const signature = req.headers['x-wc-webhook-signature'];
  const secret = process.env.WOOCOMMERCE_WEBHOOK_SECRET;
  
  if (!verifyWooCommerceWebhook(req.body, signature, secret)) {
    return res.status(400).send('Invalid signature');
  }
  
  const payload = JSON.parse(req.body);
  const topic = req.headers['x-wc-webhook-topic'];
  
  console.log(`Received ${topic} event:`, payload.id);
  res.status(200).send('OK');
});
```

### Next.js API Route (App Router)

```typescript
import crypto from 'crypto';
import { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const signature = request.headers.get('x-wc-webhook-signature');
  const secret = process.env.WOOCOMMERCE_WEBHOOK_SECRET;
  
  const rawBody = await request.text();
  
  if (!verifyWooCommerceWebhook(rawBody, signature, secret)) {
    return new Response('Invalid signature', { status: 400 });
  }
  
  const payload = JSON.parse(rawBody);
  const topic = request.headers.get('x-wc-webhook-topic');
  
  console.log(`Received ${topic} event:`, payload.id);
  return new Response('OK', { status: 200 });
}
```

### FastAPI Handler

```python
import hmac
import hashlib
import base64
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

def verify_woocommerce_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    if not signature or not secret:
        return False
    
    hash_digest = hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256
    ).digest()
    expected_signature = base64.b64encode(hash_digest).decode()
    
    return hmac.compare_digest(signature, expected_signature)

@app.post('/webhooks/woocommerce')
async def handle_webhook(request: Request):
    raw_body = await request.body()
    signature = request.headers.get('x-wc-webhook-signature')
    secret = os.getenv('WOOCOMMERCE_WEBHOOK_SECRET')
    
    if not verify_woocommerce_webhook(raw_body, signature, secret):
        raise HTTPException(status_code=400, detail='Invalid signature')
    
    payload = await request.json()
    topic = request.headers.get('x-wc-webhook-topic')
    
    print(f"Received {topic} event: {payload.get('id')}")
    return {'status': 'success'}
```

## Common Event Types

| Event | Triggered When | Common Use Cases |
|-------|----------------|------------------|
| `order.created` | New order placed | Send confirmation emails, update inventory |
| `order.updated` | Order status changed | Track fulfillment, send notifications |
| `order.deleted` | Order deleted | Clean up external systems |
| `product.created` | Product added | Sync to external catalogs |
| `product.updated` | Product modified | Update pricing, inventory |
| `customer.created` | New customer registered | Welcome emails, CRM sync |
| `customer.updated` | Customer info changed | Update profiles, preferences |

## Environment Variables

```bash
WOOCOMMERCE_WEBHOOK_SECRET=your_webhook_secret_key
```

## Headers Reference

WooCommerce webhooks include these headers:

- `X-WC-Webhook-Signature` - HMAC SHA256 signature (base64)
- `X-WC-Webhook-Topic` - Event type (e.g., "order.created")
- `X-WC-Webhook-Resource` - Resource type (e.g., "order")
- `X-WC-Webhook-Event` - Action (e.g., "created")
- `X-WC-Webhook-Source` - Store URL
- `X-WC-Webhook-ID` - Webhook ID
- `X-WC-Webhook-Delivery-ID` - Unique delivery ID

## Local Development

For local webhook testing, install Hookdeck CLI:

```bash
```

Then start the tunnel:

```bash
npx hookdeck-cli listen 3000 woocommerce --path /webhooks/woocommerce
```

No account required. Provides local tunnel + web UI for inspecting requests.

## Reference Materials

- `overview.md` - What WooCommerce webhooks are, common event types
- `setup.md` - Configure webhooks in WooCommerce admin, get signing secret
- `verification.md` - Signature verification details and gotchas
- `examples/` - Complete runnable examples per framework

## Recommended: webhook-handler-patterns

For production-ready webhook handlers, also install the webhook-handler-patterns skill for:

- <a href="https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md">Handler sequence</a>
- <a href="https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md">Idempotency</a>  
- <a href="https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md">Error handling</a>
- <a href="https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md">Retry logic</a>

## Related Skills

- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhooks with HMAC verification
- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify store webhooks with HMAC verification
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhooks
- [paddle-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/paddle-webhooks) - Paddle billing webhooks
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure

© hookdeck · MIT · hookdeck/webhook-skills

Similar skills

All skills for Backend and APIs →

From the same set39

The whole set →
paddle-webhooks paddle-webhooks helps your coding agent verify HMAC-SHA256 signatures and process Paddle billing webhooks properly. CX Codex +1 258installs sendgrid-webhooks sendgrid-webhooks is a Claude Code skill that sets up SendGrid webhook handlers, validates signatures, and processes email events for delivery tracking and verification debugging. CX Codex +1 253installs elevenlabs-webhooks Teaches your coding assistant how to verify and handle ElevenLabs webhooks. Useful when implementing call transcript handlers or debugging signature validation. CX Codex +1 237installs hookdeck-event-gateway Connects Hookdeck Event Gateway — webhook infrastructure with queue, retries and monitoring. CX Codex +1 214installs clerk-webhooks This skill guides you through receiving Clerk webhooks and checking their signatures. Use it when building handlers for user, session, or organization events. CX Codex +1 210installs vercel-webhooks Skill for receiving and verifying Vercel webhooks directly in code. Handles webhook setup, signature verification debugging, and reacting to deployment and project events. CX Codex +1 204installs postmark-webhooks Configures handlers for Postmark webhooks. It processes bounces, opens, clicks, spam complaints, and inbound messages. CX Codex +1 203installs openai-webhooks A skill for receiving and verifying OpenAI webhooks. Use it to process fine-tuning events, batch completions, and realtime API callbacks with built-in signature validation. CX Codex +1 202installs

Project sponsors

Companies that keep this analytics open