woocommerce-webhooks — скилл для Claude Code: приём вебхуков
Скилл woocommerce-webhooks помогает принимать и проверять вебхуки WooCommerce в Node.js и Python. Защищает эндпоинты через сверку HMAC-подписей событий заказов и товаров.
MIT 213 установок ★ 103 обновлён 2026-10-22
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-codeЧто делает woocommerce-webhooks
Скилл даёт готовые паттерны для обработки входящих событий интернет-магазинов на WooCommerce. Внутри — логика сверки подписи X-WC-Webhook-Signature через SHA-256 HMAC в кодировке base64 и безопасное сравнение хешей без утечек по времени.
Код рассчитан на Express, Next.js App Router и FastAPI. Критическое требование: для валидации подписи обязательно сохранять необработанный запрос (raw body). Если парсер JSON изменит тело до вычисления HMAC, сверка гарантированно вернёт ошибку.
Для локальной отладки входящих запросов используется Hookdeck CLI с пробросом туннеля через порт 3000. Секретный ключ задаётся переменной окружения WOOCOMMERCE_WEBHOOK_SECRET.
Какие задачи решает
- проверить HMAC SHA-256 подпись вебхука WooCommerce
- настроить обработчик событий
order.createdиorder.updatedв Express или FastAPI - обработать входящие хуки магазина в Next.js App Router
- протестировать приём хуков локально через туннель Hookdeck CLI
Примеры запросов агенту
- Напиши обработчик вебхуков WooCommerce на Express с проверкой подписи
- Как проверить заголовок X-WC-Webhook-Signature в маршруте Next.js App Router?
- Покажи, как обработать событие order.created в FastAPI с безопасным сравнением хеша
Как установить woocommerce-webhooks
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-code2Вручную: положить файлы
~/.claude/skills/woocommerce-webhooks/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/woocommerce-webhooks/
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a codex2Вручную: положить файлы
.agents/skills/woocommerce-webhooks/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a cursor2Вручную: положить файлы
.cursor/skills/woocommerce-webhooks/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/woocommerce-webhooks2Вручную: положить файлы
.github/skills/woocommerce-webhooks/SKILL.md1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a gemini-cli2Командой платформы
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/woocommerce-webhooksВручную: положить файлы
.devin/skills/woocommerce-webhooks/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о woocommerce-webhooks
Как установить woocommerce-webhooks в Claude Code?
Выполните команду npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-code. Файл навыка запишется в ~/.claude/skills/woocommerce-webhooks/SKILL.md.
Что делает скилл woocommerce-webhooks?
Он предоставляет готовые функции сверки подписей и шаблоны эндпоинтов для приёма событий заказов, товаров и профилей клиентов из WooCommerce.
Почему проверка подписи вебхука завершается ошибкой?
Для вычисления HMAC нужен оригинальный raw body. Если промежуточный слой Express или FastAPI успел распарсить JSON до вызова проверки, хеши не совпадут.
Исходный текст
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