/webhook-designer

name: memstack-automation-webhook-designer
description: "Use this skill when the user says 'webhook', 'webhook handler', 'webhook endpoint', 'receive events', 'HMAC verification', 'idempotency', or needs secure webhook handlers with signature verification, retry handling, and dead letter queues. Do NOT use for full n8n workflows or scheduled tasks."
version: 1.0.0
license: "Proprietary, MemStack™ Pro by CW Affiliate Investments LLC. See LICENSE.txt"

Webhook Designer: Designing webhook handler...

*Creates secure webhook handlers with endpoint design, payload validation, HMAC signature verification, retry logic, idempotency, logging, and dead letter queues.*

Activation

When this skill activates, output:

`Webhook Designer: Designing webhook handler...`

Then execute the protocol below.

Context Guard

| Context | Status | |---------|--------| | User says "webhook", "webhook handler", "webhook endpoint" | ACTIVE | | User says "receive events", "HMAC verification", "idempotency" | ACTIVE | | User wants to build an endpoint that receives external events | ACTIVE | | User wants a full n8n automation workflow | DORMANT: use n8n Workflow Builder | | User wants a scheduled/cron job | DORMANT: use Cron Scheduler |

Common Mistakes

| Mistake | Why It's Wrong | |---------|---------------| | "Skip signature verification" | Without HMAC, anyone can send fake events to your endpoint. Always verify. | | "Process synchronously" | Long processing blocks the response. Return 200 immediately, process async. | | "No idempotency" | Senders retry on timeout. Without idempotency keys, you'll process duplicates. | | "Ignore retry headers" | Senders include retry count and delivery ID. Log them for debugging. | | "Return detailed errors" | Never expose internals. Return 200 (accepted) or 400 (bad request), nothing more. |

Protocol

Step 1: Gather Webhook Requirements

If the user hasn't provided details, ask:

> 1. **Source**: what service sends the webhook? (Stripe, GitHub, Shopify, custom) > 2. **Events**: which events do you need to handle? (e.g., payment.completed, push) > 3. **Payload**: what does the payload look like? (JSON schema or example) > 4. **Auth**: how does the source authenticate? (HMAC, bearer token, IP whitelist) > 5. **Processing**: what should happen when an event arrives? > 6. **Framework**: what's your stack? (Next.js, Express, FastAPI, etc.)

Step 2: Design Endpoint

**Endpoint pattern:**

POST /api/webhooks/{source}
Headers:
  Content-Type: application/json
  X-Webhook-Signature: {hmac_signature}
  X-Webhook-ID: {delivery_id}
  X-Webhook-Timestamp: {unix_timestamp}
Body: {event payload}

Response: 200 OK (within 5 seconds)

**Handler flow:**

Request received
  ├── 1. Read raw body (before JSON parsing)
  ├── 2. Verify signature (HMAC-SHA256)
  │     └── Fail → 401 Unauthorized (log attempt)
  ├── 3. Parse JSON payload
  │     └── Fail → 400 Bad Request
  ├── 4. Check idempotency (delivery ID seen before?)
  │     └── Duplicate → 200 OK (skip processing)
  ├── 5. Validate event type (is it one we handle?)
  │     └── Unknown → 200 OK (acknowledge but ignore)
  ├── 6. Return 200 OK immediately
  └── 7. Process event asynchronously
        └── Fail → Write to dead letter queue

Step 3: Implement Signature Verification

**HMAC-SHA256 verification (most common):**

// Next.js / Express example
import crypto from 'crypto';

function verifyWebhookSignature(
  rawBody: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

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

**Provider-specific patterns:**

| Provider | Header | Algorithm | Prefix | |----------|--------|-----------|--------| | Stripe | `Stripe-Signature` | HMAC-SHA256 | `t=timestamp,v1=signature` | | GitHub | `X-Hub-Signature-256` | HMAC-SHA256 | `sha256=` | | Shopify | `X-Shopify-Hmac-Sha256` | HMAC-SHA256 (base64) | None | | Twilio | `X-Twilio-Signature` | HMAC-SHA1 (base64) | None | | Slack | `X-Slack-Signature` | HMAC-SHA256 | `v0=` | | Custom | `X-Webhook-Signature` | HMAC-SHA256 (hex) | None |

**Timestamp validation (replay protection):**

function verifyTimestamp(timestamp: number, toleranceSeconds = 300): boolean {
  const now = Math.floor(Date.now() / 1000);
  return Math.abs(now - timestamp) <= toleranceSeconds;
}

Step 4: Implement Idempotency

// Using a database table for idempotency
async function isProcessed(deliveryId: string): Promise<boolean> {
  const existing = await db.webhookDeliveries.findUnique({
    where: { deliveryId }
  });
  return !!existing;
}

async function markProcessed(deliveryId: string, event: string): Promise<void> {
  await db.webhookDeliveries.create({
    data: {
      deliveryId,
      event,
      processedAt: new Date(),
      // Auto-delete after 7 days to prevent unbounded growth
    }
  });
}

**Idempotency table schema:**

CREATE TABLE webhook_deliveries (
  delivery_id  VARCHAR(255) PRIMARY KEY,
  event_type   VARCHAR(100) NOT NULL,
  processed_at TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
  payload_hash VARCHAR(64),  -- Optional: detect payload changes
  created_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW()
);

-- Auto-cleanup: delete records older than 7 days
CREATE INDEX idx_webhook_deliveries_created ON webhook_deliveries(created_at);

Step 5: Build Event Router

// Event handler registry
const handlers: Record<string, (payload: any) => Promise<void>> = {
  'payment.completed': handlePaymentCompleted,
  'payment.failed':    handlePaymentFailed,
  'customer.created':  handleCustomerCreated,
  // Add handlers as needed
};

async function routeEvent(eventType: string, payload: any): Promise<void> {
  const handler = handlers[eventType];
  if (!ha