woocommerce-webhooks

What this skill does

# 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