Skip to content
Skills Library
Programming · Testing

webhook-integration-testing

/webhook-integration-testing

Build and test webhook integrations locally — capture real webhooks as fixtures, verify HMAC signatures correctly (including timestamp freshness against replay), replay captures at your handler while developing. Use whenever the user integrates with webhooks (Stripe, GitHub, Shopify, payment systems, CRMs), says "webhook", "callback", "signature verification fails", "how do I test webhooks locally", "is my webhook handler working", sets up a webhook endpoint, or a production webhook integration is dropping events. Not for intercepting other people's webhooks or bypassing signature checks.

Repository
hookbench ↗
Licence
MIT
Last repository change
31.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 31.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Build and test webhook integrations locally — capture real webhooks as fixtures, verify HMAC signatures correctly (including timestamp freshness against replay), replay captures at your handler while developing. Use whenever the user integrates with webhooks (Stripe, GitHub, Shopify, payment systems, CRMs), says "webhook", "callback", "signature verification fails", "how do I test webhooks locally", "is my webhook handler working", sets up a webhook endpoint, or a production webhook integration is dropping events. Not for intercepting other people's webhooks or bypassing signature checks.

Triggers from the description

webhookcallbacksignature verification failshow do I test webhooks locallyis my webhook handler working
Original author description

Build and test webhook integrations locally — capture real webhooks as fixtures, verify HMAC signatures correctly (including timestamp freshness against replay), replay captures at your handler while developing. Use whenever the user integrates with webhooks (Stripe, GitHub, Shopify, payment systems, CRMs), says "webhook", "callback", "signature verification fails", "how do I test webhooks locally", "is my webhook handler working", sets up a webhook endpoint, or a production webhook integration is dropping events. Not for intercepting other people's webhooks or bypassing signature checks.

How it works

  1. 1. Capture real webhooks as fixtures
  2. 2. Verify signatures the way the sender means them
  3. 3. Develop the handler against fixtures, not live traffic
  4. 4. The exposure problem (handler never gets called)
  5. 5. Report
  6. Scope
Original SKILL.md headings · 64 lines, 631 words
SKILL.md preview
---
name: webhook-integration-testing
description: Build and test webhook integrations locally — capture real webhooks as fixtures, verify HMAC signatures correctly (including timestamp freshness against replay), replay captures at your handler while developing. Use whenever the user integrates with webhooks (Stripe, GitHub, Shopify, payment systems, CRMs), says "webhook", "callback", "signature verification fails", "how do I test webhooks locally", "is my webhook handler working", sets up a webhook endpoint, or a production webhook integration is dropping events. Not for intercepting other people's webhooks or bypassing signature checks.
---

# Webhook integration testing

A webhook integration fails in exactly three ways: your handler never gets called (exposure/tunnel problem), the signature doesn't verify (secret/serialization problem), or the handler is wrong (logic problem). This skill separates them mechanically instead of guessing — capture real traffic, verify signatures with the exact bytes, replay on demand.

Install the CLI:

```bash
pip install hookbench
```

## 1. Capture real webhooks as fixtures

Run the local receiver and point the sender at it (or at a tunnel to it):

```bash
hookbench receive --port 8080 --secret-file secret.txt --out captured.ndjson
```

Every incoming request is printed live with its signature verdict and stored as a fixture (timestamp, path, headers, body, verdict). The fixture file is the ground truth for everything that follows: real payloads, real headers, exactly the bytes the sender sent.

**Serialization is the classic trap:** signature verification is over *exact bytes*. If anything between sender and your code re-serializes the JSON (a proxy pretty-printing the body, a framework re-ordering keys), the signature breaks while the payload "looks the same". That's why fixtures store raw bytes-as-text, and why verification must use the raw request body — never a parsed-and-re-dumped copy.

## 2. Verify signatures the way the sender means them

```bash
hookbench verify --payload body.bin --signature "sha256=abc…" --secret-file secret.txt
```

Schemes differ across vendors, and each mistake has a name:

- **raw payload** (`X-Signature: sha256=hex(payload)`) — GitHub style;
- **timestamped** (`t=<ts>,v1=hex(ts.payload)`) — Stripe style: the signature covers `<timestamp>.<body>`, and an old timestamp must be rejected even with a valid signature, otherwise anyone who once captured a payload can replay it forever;
- custom headers (a vendor prefix like `Stripe-Signature` vs `X-Hub-Signature-256`) — the algorithm is the same, the header name and message layout differ.

`hookbench verify` covers raw and timestamped schemes with a constant-time comparison and a freshness tolerance (`--require-timestamp`, `--tolerance 300`). If verification fails while the payload looks right, the usual suspects in order: comparing the *parsed-then-re-serialized* body instead of raw bytes; wrong secret (test vs prod keys); header name mismatch; including the `sha256=` prefix in the digest input (or not).

## 3. Develop the handler against fixtures, not live traffic

```bash
hookbench replay captured.ndjson --url http://localhost:9000/handler --secret-file secret.txt
```

Replay re-signs each fixture with a fresh timestamp (so your own replay doesn't trip your replay protection; `--keep-original-signatures` replays the captured bytes as-is for comparison) and POSTs them to your handler. Failing one fixture now is a test failure with a name, not a 2 a.m. page.

This is also the correct way to test rare events: capture the real "payment.succeeded" once, replay it a hundred times while developing, and keep the fixtures in the repo as the integration's test suite.

## 4. The exposure problem (handler never gets called)

Localhost isn't reachable from the internet; expose the receiver through a tunnel only when the *sender* must be real. For everything else, fixtures + replay are enough — no tunnel, no third party seeing your payloads. When a tunnel is needed (verifying the sender's own retries, or testing TLS-termination behavior), the receiver still verifies signatures, so a misconfigured tunnel shows up as a verdict you can read.

## 5. Report

```text
exposure:  receiver on :8080 behind tunnel X; sender reachable, 3 events captured
signatures: 3/3 valid (sha256, raw payload); vendor docs say Stripe-style v1 — NOT used by this sender
handler:   replay of 3 fixtures: 2 processed, 1 raised KeyError on "data.object.customer"
next:      fix the handler for the missing-field case; keep captured.ndjson as the test fixture
```

## Scope

Capture and replay webhooks for integrations the user owns or is authorized to test. Verifying signatures is exactly how receivers defend themselves — this skill never helps *forge* a signature for a secret you don't hold, and fixtures with real customer payloads stay on the user's machine.

Versions

The database has no other skills named webhook-integration-testing.

Database snapshot: 13.11.2026 · package version fc3a69ca6289 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100stripe-test-cards-and-webhooks
    Use for any question or task about testing Stripe payments, including one webhook handler and checkout that fails for 3D Secure cards: test-mode keys, test cards for success, declines and 3D Secure, stripe listen to forward webhooks locally, stripe trigger fixtures, and…
  • 100opnform-webhooks
    Receive and verify OpnForm webhooks. Use when setting up OpnForm webhook integration handlers, debugging X-Webhook-Signature (sha256=<hex>) HMAC verification, or handling OpnForm form submission payloads.
  • 100bugsmash-webhooks
    Receive and verify BugSmash webhooks. Use when setting up BugSmash webhook handlers, debugging X-BugSmash-Signature verification (HMAC-SHA256 over X-Webhook-Timestamp + "." + raw body), storing the one-time bgsmsh_ secret_key, or handling new_comment, comment_replied,…
  • 100webhook-handling-verification
    Use this skill when receiving, verifying HMAC signatures, and processing third-party webhooks with replay attack prevention.
  • 100webhook-receiver-design
    Use when designing webhook endpoints (Stripe/GitHub/Slack/internal), implementing HMAC signature verification, ensuring idempotency on retries, handling out-of-order events, building dead-letter queues, or replaying historical webhooks. Triggers: signature header verification…
  • 90Linear Webhooks (Verify, Replay, DLQ)
    This skill should be used when registering, verifying, or processing Linear webhooks — HMAC signatures, replay protection, idempotency, dead-letter queues. Activates on "linear webhook", "webhook signature", "Linear-Signature", "webhook secret".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.