К основному содержанию
скилл CX Codex

woocommerce-webhooks — скилл для Claude Code: приём вебхуков

Скилл woocommerce-webhooks помогает принимать и проверять вебхуки WooCommerce в Node.js и Python. Защищает эндпоинты через сверку HMAC-подписей событий заказов и товаров.

MIT 213 установок ★ 103 обновлён 2026-10-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/woocommerce-webhooks/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
setup-zoom-webhooks официальный anthropics Скилл setup-zoom-webhooks для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI с эталонной документацией по Zoom webhooks. Включается при реализации подписок на события, проверки подписи x-zm-signature и обработки доставки. CX Codex +1 2 200установок fireflies-webhooks-events Jeremy Longshore Скилл fireflies-webhooks-events проводит агента по сборке приёмника Fireflies Webhooks V2: проверка HMAC по сырому телу, белый список событий, дедупликация и быстрый ответ 2xx. CX Codex +1 1установок firecrawl-webhooks-events Jeremy Longshore Скилл firecrawl-webhooks-events настраивает приём вебхуков Firecrawl: валидацию подписи HMAC-SHA256, дедупликацию и синхронизацию статусов. CX Codex +1 1установок webhook-receiver-hardener patricio0312rev Скилл webhook-receiver-hardener помогает проектировать защищённые эндпоинты для вебхуков. Защищает обработчики от подделки запросов, повторных доставок и сбоев сторонних сервисов. CX Codex +1 287установок clerk-webhooks clerk Скилл clerk-webhooks для Claude Code помогает создавать обработчики вебхуков Clerk с проверкой подписи. Запускается при настройке синхронизации данных и действий на событиях Clerk. CX Codex +1 55 700установок woocommerce Mindrally Набор правил разработки для WordPress и WooCommerce. Помогает писать безопасный PHP-код с хуками, кастомными типами товаров и REST API. CX Codex +1 886установок

Из того же набора39

Весь набор →
paddle-webhooks Скилл paddle-webhooks учит ИИ проверять подпись HMAC-SHA256 и обрабатывать вебхуки Paddle для подписок и транзакций. CX Codex +1 258установок sendgrid-webhooks Скилл sendgrid-webhooks помогает настроить обработчик вебхуков SendGrid, проверить подпись и разобрать события доставки писем. Пригодится при отладке интеграции и аналитики вовлечённости. CX Codex +1 253установок elevenlabs-webhooks Скилл elevenlabs-webhooks даёт ИИ-агенту инструкции для надёжного приёма и проверки вебхуков ElevenLabs. Пригодится при настройке валидации подписи и обработке транскрипций звонков. CX Codex +1 237установок hookdeck-event-gateway Подключает Hookdeck Event Gateway — инфраструктуру приёма вебхуков с очередью, повторами и мониторингом. CX Codex +1 214установок clerk-webhooks Скилл clerk-webhooks помогает написать обработчик вебхуков Clerk и проверить подпись запроса. Пригодится при настройке событий пользователей, сессий и организаций. CX Codex +1 210установок vercel-webhooks Скилл vercel-webhooks для приёма и проверки вебхуков Vercel прямо в коде. Помогает при настройке обработчиков, отладке проверки подписей и реагировании на события развёртывания и проектов. CX Codex +1 204установок postmark-webhooks Скилл postmark-webhooks для Claude Code помогает принимать и обрабатывать вебхуки Postmark. Настраивает обработку доставок, кликов, открытий, жалоб на спам и входящих сообщений. CX Codex +1 203установок openai-webhooks Скилл openai-webhooks для Claude Code принимает и проверяет вебхуки OpenAI. Обрабатывает события fine-tuning, batch API и realtime API с проверкой подписей. CX Codex +1 202установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой