webhook-verifier

name	webhook-verifier
description	Reference for cryptographic verification of payment webhooks. Cited by integration-specialist whenever it generates a webhook handler. Documents per-provider signature algorithms, timestamp tolerances, replay-protection strategies, raw-body capture per stack, and the minimum set of events each handler must route. Always use this skill (instead of recalling from training data) — webhook verification is where the integration goes silently wrong.
when_to_use	- integration-specialist is about to write or edit a webhook handler - /pagokit:doctor audits the signature pattern of an existing handler - The user asks "is my Stripe webhook signature check correct?" or equivalent
allowed-tools	Read

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
}

Express:

// Critical: register raw BEFORE express.json() globally
app.post('/api/webhook/<provider>',
  express.raw({ type: 'application/json', limit: '256kb' }),
  async (req, res) => {
    const rawBody = req.body; // Buffer because of express.raw
    const signature = req.headers['<signature-header>'];
    // ...
  }
);

FastAPI:

from fastapi import Request, HTTPException

@app.post("/api/webhook/<provider>")
async def webhook(request: Request):
    if int(request.headers.get("content-length", 0)) > 262_144:
        raise HTTPException(413)
    raw_body = await request.body() # bytes; never .json() before verify
    signature = request.headers.get("<signature-header>")
    # ...

Laravel:

$rawBody = $request->getContent(); // string
$signature = $request->header('<signature-header>');

Rails:

raw_body = request.raw_post
signature = request.headers['<signature-header>']

Per-provider details

See signatures.md for the full table:

• Signature header name
• Algorithm (HMAC-SHA256, HMAC-SHA256-with-timestamp, SHA-256-checksum)
• Timestamp tolerance in seconds
• Replay mitigation strategy (timestamp-window | event-id-dedup | both)
• Required events minimum (the switch router must handle these or log them as TODO)
• Canonical code snippet calling the provider's verifier

Error handling

Situation	Response	Why
Signature invalid	400 Bad Request, body: empty or { "error": "invalid_signature" }	Don't leak why it failed; force attacker to guess.
Body > 256 KB	413 Payload Too Large	DoS guard.
Replay (old timestamp)	400 Bad Request	Same as bad signature from the attacker's POV.
Duplicate event.id	200 OK, no-op	Idempotency: provider may legitimately retry.
Handler threw an exception	500 Internal Server Error	Provider will retry; check webhook_events_processed to dedup the retry.
Event type not handled	200 OK, log TODO	Avoid being unsubscribed for non-200 responses.

The // @pagokit:signature-verified tag

The webhook-has-signature.js validator detects standard calls (stripe.webhooks.constructEvent, Wompi.verifyEventChecksum, etc.). If you generate code that wraps verification in a helper from lib/auth/, place this tag on the handler function so the validator knows it's covered:

// @pagokit:signature-verified -- uses lib/auth/verifyStripeWebhook
export async function POST(request: Request) { … }

Bypassing the rule entirely (rare) uses the different // pagokit-ignore: syntax — see SECURITY_RULES.md Rule 3.

Anti-patterns (refuse to generate code that does any of these)

• ❌ await request.json() before signature verification — breaks the HMAC.
• ❌ Trusting event.type from the parsed JSON before verifying.
• ❌ Storing webhook secrets in process.env without checking .env is gitignored.
• ❌ Returning a non-2xx response to all unhandled events — most providers disable the endpoint after consecutive failures.
• ❌ Logging the full event body to console / Sentry.
• ❌ Verifying with STRIPE_SECRET_KEY (the API key) instead of STRIPE_WEBHOOK_SECRET (a different secret with whsec_ prefix).