Webhook Testing Tools skill for Codex

Done well means: the handler is exercised with real provider payloads before deploy, signature verification is tested with the same raw bytes the provider sends, every bug fix is replayed against the exact event that broke it, CI runs signed fixtures without a network, and no tunnel is left open afterwards.

Building the receiver itself (verification, idempotency, queues) is $webhook-receivers; sending webhooks to others is $webhook-delivery.

Inspect first

1. Read AGENTS.md for the dev server command and port; find the handler route (rg -n "webhook" src app routes --glob '!node_modules').
2. Check how the handler reads the body. Signature checks need the raw bytes (Express express.raw(), Next.js route handler await req.text(), FastAPI await request.body()). A JSON body parser in front of the route is the most common reason local tests fail.
3. Note the provider’s signature scheme and where the test signing secret comes from (.env.local).
4. Tunnels and provider CLIs need outbound network access, which the Codex sandbox may block; ask for approval or have the user run the tunnel in their own terminal.

Pick the tool

Situation	Use	Why
Provider has a forwarding CLI	Stripe CLI, gh webhook forward, Shopify CLI, Twilio CLI	Real signed events, no public URL to manage
Provider needs a public HTTPS URL	cloudflared quick tunnel or ngrok	Stable HTTPS in one command
URL must survive restarts (provider dashboard config)	ngrok reserved domain, named Cloudflare Tunnel, Tailscale Funnel	Same URL every session
GitHub or any provider, no account wanted	smee.io channel + smee-client	Persistent channel, replays from browser
Just see what the provider sends	Tunnel inspector (ngrok http://127.0.0.1:4040) or a private request bin	Headers and raw body
Regression test after a fix, CI	Saved fixture + scripts/replay_webhook.py	Deterministic, offline
Slack apps in development	Socket Mode	No inbound URL needed at all

Do not paste production payloads into public inspection sites; they contain customer data. Use test mode events or a private bin.

Provider CLIs

# Stripe: forwards test-mode events and prints a whsec_ secret for this session
stripe listen --forward-to localhost:3000/api/webhooks/stripe --events checkout.session.completed,invoice.paid
stripe trigger checkout.session.completed
stripe events resend evt_1Q...           # resend a specific past test event to the listener

# GitHub: forward repo or org webhooks (needs admin on the repo)
gh extension install cli/gh-webhook
gh webhook forward --repo=acme/api --events=pull_request,push \
  --url=http://localhost:3000/webhooks/github --secret="$GITHUB_WEBHOOK_SECRET"

# Shopify app webhooks to a local or tunnelled address
shopify app webhook trigger --topic orders/create --address https://<tunnel-host>/webhooks/shopify

The secret printed by stripe listen differs from the dashboard endpoint secret; put it in the local env file while testing.

Tunnels

cloudflared tunnel --url http://localhost:3000          # random https://<words>.trycloudflare.com, no login
ngrok http 3000                                          # random URL; inspector at http://127.0.0.1:4040
ngrok http 3000 --url https://acme-dev.ngrok.app         # reserved domain on your ngrok account
tailscale funnel 3000                                    # public URL on your tailnet's ts.net domain
npx smee-client --url https://smee.io/<channel> --target http://localhost:3000/webhooks/github

Rules:

• Expose only the dev server port, never a database or admin service. The tunnel URL is public.
• Register the tunnel URL in the provider’s test or sandbox environment only. Changing a production webhook endpoint redirects live traffic; that needs explicit user confirmation and is rarely right.
• Many frameworks reject unknown hosts (Vite server.allowedHosts, Django ALLOWED_HOSTS, Rails config.hosts); add the tunnel host in development config only.
• Stop the tunnel when done and remove the temporary endpoint from the provider dashboard.

Capture and replay

1. Capture: log the raw body and relevant headers in development (or copy from the provider’s delivery log / the ngrok inspector). Save to test/fixtures/webhooks/<provider>/<event>.json. Scrub personal data and keep the bytes otherwise unchanged.
2. Replay against the local handler with a valid signature computed from a test secret:

python3 scripts/replay_webhook.py --scheme stripe --secret "$STRIPE_WEBHOOK_SECRET" \
  test/fixtures/webhooks/stripe/checkout.session.completed.json http://localhost:3000/api/webhooks/stripe

python3 scripts/replay_webhook.py --scheme github --secret "$GITHUB_WEBHOOK_SECRET" \
  test/fixtures/webhooks/github/pull_request.opened.json http://localhost:3000/webhooks/github \
  --header X-GitHub-Event=pull_request

python3 scripts/replay_webhook.py --scheme standard --secret "$SVIX_SECRET" payload.json http://localhost:8000/hooks
python3 scripts/replay_webhook.py --scheme hmac --sig-header X-Signature --secret "$HOOK_SECRET" \
  payload.json http://localhost:3000/hooks --dry-run

The script sends the file byte for byte, signs it with the chosen scheme (stripe, github, standard for Standard Webhooks / Svix, hmac for hex HMAC-SHA256 in a named header, or none), prints the status and response body, warns when the target is not localhost, and exits 1 on a non-2xx response. --dry-run prints the headers without sending. Schemes that use base64 HMAC (Shopify) or timestamps in other formats need a small adaptation; check the provider docs.

3. Replay twice to prove idempotency: the second delivery must not create a second side effect.
4. Replay in production only through the provider’s own “resend” feature, after the user confirms; side effects (emails, fulfilment, charges) run again.

Automated tests

Put signed fixtures in the normal test suite so CI needs no network:

import crypto from 'node:crypto';
import request from 'supertest';

const raw = fs.readFileSync('test/fixtures/webhooks/stripe/invoice.paid.json');
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac('sha256', 'whsec_test').update(`${t}.${raw}`).digest('hex');

it('processes invoice.paid once', async () => {
  for (let i = 0; i < 2; i++) {
    await request(app).post('/api/webhooks/stripe')
      .set('Stripe-Signature', `t=${t},v1=${v1}`).set('Content-Type', 'application/json')
      .send(raw).expect(200);
  }
  expect(await db.invoices.count({ status: 'paid' })).toBe(1);
});

it('rejects a tampered body', async () => {
  await request(app).post('/api/webhooks/stripe')
    .set('Stripe-Signature', `t=${t},v1=${v1}`).set('Content-Type', 'application/json')
    .send(Buffer.concat([raw, Buffer.from(' ')])).expect(400);
});

Cover at least: valid signature, tampered body, expired timestamp, duplicate delivery, unknown event type (should return 2xx and be ignored), and handler failure (should return 5xx so the provider retries).

Debugging failed deliveries

Symptom	Likely cause
Signature mismatch locally, works nowhere	Body parsed and re-serialised before hashing; wrong secret (dashboard vs CLI)
Works locally, fails in production	Proxy or framework changes the body (compression, charset), or prod secret not set
Provider shows timeouts	Handler does work inline; acknowledge first, process in a queue
404 or 405 through the tunnel	Wrong path or trailing slash; tunnel pointing at the wrong port
403 / “Invalid host” through the tunnel	Host allowlist in the dev server
Events arrive out of order	Normal; fetch current state from the API instead of trusting event order

Verification

• One real test-mode event from the provider reached the local handler and returned 2xx.
• Signed fixture replays pass in CI with no network; tampered and stale variants fail.
• Duplicate replay leaves exactly one side effect.
• Tunnels stopped and temporary provider endpoints removed; no production endpoint changed.

Output

Report: tools used, endpoints registered (and removed), fixtures added, test cases covering signature, idempotency and failure paths, and any production replays the user approved.