Webhook Debugger

---
name: webhook-debugger
description: |
  Trigger when the user asks to debug webhook delivery, why a webhook isn't
  firing, or how to inspect a failing webhook. Phrases: "webhook not working",
  "webhook failing", "webhook retries", "signature verification fails".
allowed-tools:
  - Bash(curl *)
  - Bash(stripe listen *)
  - Read
  - Grep
---

# Webhook Debugger

Diagnose a webhook that isn't firing, is firing but being rejected, or is
firing but not being processed. Covers delivery, signature, and handler.

## Prerequisites

- Webhook URL configured on the sender side (Stripe, GitHub, etc.)
- Access to logs on both sides

## Steps

1. **Determine where the failure is.** There are three failure zones:
   - **Delivery** - sender never reached your endpoint
   - **Rejection** - you returned non-2xx
   - **Processing** - you returned 2xx but nothing happened

2. **For delivery failures** check the sender's dashboard:
   - Stripe: `stripe events list` and the dashboard's Webhooks section
   - GitHub: Settings > Webhooks > Recent deliveries
   - Look for DNS errors, timeouts, non-2xx responses from your end

3. **Test the endpoint is reachable:**
   ```bash
   curl -X POST https://your.app/api/webhooks/stripe \
     -H "Content-Type: application/json" \
     -d '{}'
   ```
   Should return a well-defined error (e.g., missing signature), not a 404.

4. **For signature rejection** - the #1 webhook bug. Three common causes:
   - **Body reading order.** Signature is computed over raw body. If you
     parse JSON before computing the signature, the bytes differ (whitespace,
     field order). Read raw body, compute signature, THEN parse.
   - **Wrong secret.** Dev/prod secrets differ. Check which env you're using.
   - **Clock skew.** Signatures often have a timestamp; if your server's
     clock is off by more than the tolerance, all signatures fail.

5. **For local testing use the sender's CLI:**
   ```bash
   stripe listen --forward-to localhost:3000/api/webhooks/stripe
   gh webhook forward --repo=owner/repo --events=pull_request --url=http://localhost:3000/api/webhooks/github
   ```

6. **For processing failures** - endpoint returns 2xx but side effects
   don't happen:
   - Return 2xx ONLY after the side effect succeeds, OR enqueue the work
     and return 2xx immediately. Returning 2xx then failing async loses data.
   - Add idempotency keys. Webhooks retry. Your handler must be safe under
     duplicate delivery.

## Checklist for a new webhook handler

1. Verify signature with raw body
2. Parse the event type
3. Check idempotency key before processing
4. Do the work (or enqueue)
5. Record the webhook event ID for auditing
6. Return 2xx

## Output

- Identified failure zone (delivery/rejection/processing)
- Reproduction steps
- Fix applied (signature code, idempotency, or deploy config)
- Integration test simulating the webhook