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
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-codeWhat 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.createdand 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-code2Manually: put the files in place
~/.claude/skills/woocommerce-webhooks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/woocommerce-webhooks/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a codex2Manually: put the files in place
.agents/skills/woocommerce-webhooks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a cursor2Manually: put the files in place
.cursor/skills/woocommerce-webhooks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/woocommerce-webhooks2Manually: put the files in place
.github/skills/woocommerce-webhooks/SKILL.md1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a gemini-cli2Platform CLI
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/woocommerce-webhooksManually: put the files in place
.devin/skills/woocommerce-webhooks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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