Webhook Handler Agent Skill

---
description: Receive webhooks, signature verification, retry logic, and idempotency patterns.
homepage: https://yepapi.com/skills/webhook-handler
metadata:
  tags: [webhooks, events, signatures, integrations]
---

# Webhook Handler

## Rules

- Always verify webhook signatures — never trust unverified payloads
- Raw body for signature verification — use `request.text()` or disable body parsing for webhook routes
- Idempotency: store processed event IDs, skip duplicates — webhooks are delivered at-least-once
- Return 200 quickly — do heavy processing in a background job/queue, not in the handler
- Stripe: `stripe.webhooks.constructEvent(rawBody, sig, endpointSecret)`
- GitHub: HMAC-SHA256 — `crypto.timingSafeEqual(computedSig, headerSig)`
- Svix: `wh.verify(rawBody, headers)` from `svix` package
- Log all incoming webhooks with event type, ID, and timestamp for debugging
- Type-narrow on event type: `switch (event.type) { case "checkout.session.completed": ... }`

## Patterns

```ts
// Next.js App Router webhook route
export async function POST(req: Request) {
  const rawBody = await req.text();
  const sig = req.headers.get("stripe-signature")!;

  let event;
  try {
    event = stripe.webhooks.constructEvent(rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  // Idempotency check
  const existing = await db.webhookEvent.findUnique({ where: { eventId: event.id } });
  if (existing) return new Response("Already processed", { status: 200 });

  await db.webhookEvent.create({ data: { eventId: event.id, type: event.type } });

  switch (event.type) {
    case "checkout.session.completed":
      await handleCheckoutComplete(event.data.object);
      break;
  }

  return new Response("OK", { status: 200 });
}
```

## Avoid

- Skipping signature verification — this is a critical security vulnerability
- Doing slow work inside the webhook handler — respond fast, process async
- Assuming webhooks arrive in order — use event timestamps to resolve conflicts
- Missing idempotency — webhooks can be retried and delivered multiple times