webhook-designer

Files (1)

• SKILL.md

SKILL.md (first lines)

# 🪝 Webhook Designer — Secure Webhook Handler
*Build production-grade webhook endpoints with signature verification, idempotency, retry handling, and dead letter queues.*

## Activation

When this skill activates, output:

`🪝 Webhook Designer — Designing your webhook handler...`

| Context | Status |
|---------|--------|
| **User says "webhook", "webhook handler", "webhook endpoint"** | ACTIVE |
| **User needs to receive events from an external service** | ACTIVE |
| **User mentions HMAC, signature verification, or idempotency** | ACTIVE |
| **User wants to send webhooks (not receive)** | ACTIVE — design outbound delivery |
| **User wants a full n8n workflow (webhook is just the trigger)** | DORMANT — see n8n-workflow-builder |
| **User wants a scheduled task (not event-driven)** | DORMANT — see cron-scheduler |

## Protocol

### Step 1: Gather Inputs

Ask the user for:
- **Event type**: What event triggers the webhook? (payment completed, form submitted, deploy finished, etc.)
- **Source system**: Who sends it? (Stripe, GitHub, Shopify, SendGrid, custom)
- **Target system**: What should happen when received? (update database, send notification, trigger pipeline)
- **Payload format**: JSON? Form-encoded? Known schema?
- **Runtime**: Express, Next.js API route, Fastify, serverless function?

### Step 2: Design Webhook Endpoint

```javascript
// Route: POST /api/webhooks/[source]
// Auth: Signature verification (no bearer token)
// Rate limit: Standard or elevated for known webhook sources

router.post('/api/webhooks/[source]', async (req, res) => {
  // 1. Verify signature
  // 2. Parse and validate payload
  // 3. Check idempotency
  // 4. Process event
  // 5. Return 200 quickly
});
```

**Design decisions:**
- Respond with 200 immediately, process asynchronously if > 5s work
- Always return 200 for valid signatures (even if event is ignored)
- Return 400 only for malformed requests, 401 for bad signatures
- Log the raw body before any processing for debugging

### Step 3: Signature Verification

Provide code for the specific source system:

**HMAC-SHA256 pattern (Stripe, GitHub, Shopify):**

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

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  // Timing-safe comparison prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

**Source-specific patterns:**
- **Stripe**: `stripe.webhooks.constructEvent(body, sig, endpointSecret)`
- **GitHub**: `X-Hub-Signature-256` header, `sha256=` prefix
- **Shopify**: `X-Shopify-Hmac-SHA256` header, base64 encoding
- **SendGrid**: Event Webhook signature verification
- **Custom**: Document the signing algorithm used

**Additional security layers:**
- Verify `Content-Type` header matches expected format
- Reject requests with missing or empty signature headers
- Log failed verification attempts (potential attack indicator)

### Step 4: Payload Validation

Define the expected schema:

```javascript
// Zod schema example
const WebhookPayload = z.object({
  event: z.enum(['payment.completed', 'payment.failed', 'refund.created']),
  data: z.object({
    id: z.string(),
    amount: z.number(),
    currency: z.string().length(3),
    customer_email: z.string().email(),
    metadata: z.record(z.unknown()).optional(),
  }),
  timestamp: z.string().datetime(),
  webhook_id: z.string(), // For idempotency
});

// Validate
const result = WebhookPayload.safeParse(req.body);
if (!result.success) {
  console.error('Invalid webhook payload:', result.error.issues);
  return res.status(400).json({ error: 'Invalid payload' });
}
```

**Validation rules:**
- Validate structure, not just presence (type-check every field)
- Allow unknown fields (source APIs add new fields without notice)
- Log validation failures with the raw payload for debugging
- Version your schema — source APIs evolve

From jtucker9/mystuff, MIT.

More from jtucker9/mystuff