webhook-verifier

webhook-verifier

You are the single source of truth for "how a webhook is verified for provider X on stack Y". When generating webhook code, integration-specialist reads this skill and the per-provider details in signatures.md, and produces a handler that:

1. Captures the raw request body (NOT parsed).
2. Verifies the cryptographic signature using the provider's canonical method.
3. Applies replay protection (timestamp window OR event-id dedup, per providers.json).
4. Routes the verified event to the appropriate handler.
5. Returns the correct HTTP status code (200 OK for valid events; 400 for bad signature; 401 for replay).
6. Caps the body at 256 KB before reading.
7. Logs only event.id, event.type, event.created — never the full payload.

The verification contract

A correct webhook handler has this shape (language-neutral):

1. Read Content-Length header → if > 256 KB, return 413.
2. Read raw body (bytes, NOT parsed JSON).
3. Read signature header (provider-specific).
4. Verify signature → if invalid, return 400 with no leak about why.
5. Parse JSON from raw body now that signature is verified.
6. Apply replay protection:
   a. If signature includes timestamp: check `event_timestamp` within tolerance.
   b. Otherwise: check event.id against webhook_events_processed table.
7. If duplicate (already processed): return 200 OK (idempotent), do nothing.
8. Dispatch to handler by event.type.
9. Mark event as processed.
10. Return 200 OK.

Raw-body capture per stack (Rule 5)

Next.js App Router — the most common mistake:

// app/api/webhook/<provider>/route.ts
export const runtime = 'nodejs'; // NOT 'edge'

export async function POST(request: Request) {
  const rawBody = await request.text(); // raw string
  const signature = request.headers.get('<signature-header>');
  // pass rawBody (string) to provider's verifier
}

Next.js Pages Router:

// pages/api/webhook/<provider>.ts
export const config = { api: { bodyParser: false } };

import { buffer } from 'micro';

export default async function handler(req, res) {
  const rawBody = await buffer(req); // Buffer
  // pass rawBody.toString() to verifier
}