fasthook 2.0.0

A simple local webhook receiver and relay tool

fasthook 🪝

A dead-simple local webhook receiver for testing and development. Because sometimes you just need to see what’s being sent to your endpoint.

pip install fasthook
fasthook listen 3000

Just like that, you're catching webhooks at: 👉 http://localhost:3000

---

Why fasthook?

When you’re integrating Stripe, PayPal, Clerk, GitHub, or any service that fires webhooks, you hit the same problem:

You can’t see what they’re sending without tunnels, accounts, dashboards, or annoying setup.

fasthook fixes that: ✅ No ngrok ✅ No cloud dashboard ✅ No signup ❗ Just a lightweight local server that captures everything.

---

🚀 What's New in v2.0.0

fasthook 2.0 is a complete upgrade, built to move from “dev toy” → production-ready tooling.

⚡ Performance & Reliability

• Fully async architecture (FastAPI + Uvicorn)
• Connection pooling for forwarding
• Bounded queues prevent memory bloat
• Configurable concurrency & rate limits
• Graceful shutdown + full cleanup
• Structured logging with optional log rotation

🎭 Mock Server Mode

• Scripted responses for any endpoint
• Dynamic sequences (return different responses per call)
• Per-route delays, status codes, and bodies
• Built-in health & stats endpoints
• Wildcard paths (/api/*) supported

🔄 Event Replay

• Replay saved events with original timing
• Adjustable playback speed (0.5x → 10x)
• Rate limiting to avoid flooding targets
• Replays to any URL
• Great for load testing or staging environments

🧰 Developer Quality-of-Life

• Pretty printed JSON
• Quiet mode for CI
• Save-event output as newline-delimited JSON
• Automatic retry logic (exponential backoff)
• Debug mode for introspecting requests

---

Installation

pip install fasthook

Requires Python 3.8+.

---

Quick Start

Start listening on port 3000:

fasthook listen 3000

Now any request to http://localhost:3000/* is logged with full details.

---

Features

🔍 Inspect Everything

• Method, path, headers, IP, query params
• JSON body or raw body
• Pretty JSON display

💾 Save Webhooks

• Save all events to newline-delimited JSON
• Works great with jq, pandas, or custom scripts

🔁 Forward Webhooks

• Forward to another endpoint
• Retry with exponential backoff
• Connection pooling
• Concurrency controls

🎭 Mock Server

• Script dynamic responses
• Wildcards supported
• Per-call sequences
• Built-in status, logs, delays

🔄 Event Replay

• Replay saved events exactly as received
• Preserve timing or speed up
• Target any URL
• Limit RPS to avoid overload

⚙️ Production-Ready

• Logging (stdout/file)
• Log rotation
• Resource cleanup
• Rate limiting
• Graceful shutdown

---

Usage Examples

Listen on port 3000

fasthook listen 3000

Save events

fasthook listen 3000 --save events.json

Forward with retries

fasthook listen 3000 --forward http://example.com/webhook --forward-retries 3

Mock server

fasthook listen 3000 --mock responses.json

Replay events (2× faster)

fasthook replay events.json --target http://localhost:8000 --rate 2.0

Full setup

fasthook listen 3000 --save events.json --forward http://example.com/webhook --pretty --exit-after 100

---

Mock Server Example (responses.json)

{
  "defaults": {
    "status": 200,
    "delay": 0,
    "body": {"status": "ok"}
  },
  "routes": {
    "/webhook": {
      "POST": {
        "status": 201,
        "body": {"success": true, "id": "123"},
        "delay": 0.5
      },
      "GET": {
        "status": 200,
        "body": {"message": "Hello World"}
      }
    },
    "/api/*": {
      "ANY": {
        "status": 404,
        "body": {"error": "Not found"}
      }
    }
  }
}

Run it:

fasthook mock 3000 --spec responses.json

---

What It Looks Like

============================================================
[2025-01-15T10:30:45.123Z] POST /webhook/stripe
IP: 192.168.1.100
Query: {'test': 'true'}
Headers:
  content-type: application/json
  stripe-signature: t=123456,v1=abcdef...
JSON Body:
{
  "id": "evt_123",
  "type": "payment_intent.succeeded",
  ...
}
============================================================

---

Command Reference

fasthook listen

PORT

--save PATH
--forward URL
--forward-retries N
--forward-concurrency N
--pretty
--quiet
--log-file PATH
--log-level LEVEL
--log-rotate
--exit-after N
--mock SPEC
--debug
--host HOST

fasthook replay

EVENTS_FILE

--rate MULTIPLIER
--once
--target URL
--delay SECONDS
--max-rps RATE

fasthook mock

PORT

--spec PATH
--host HOST
--quiet

---

Saved Events Format

Events saved with --save are newline-delimited JSON:

{"timestamp": "...", "method": "POST", "path": "...", "headers": {...}, "json": {...}}

Perfect for use with:

jq
pandas
grep
custom scripts

---

Common Use Cases

Local Stripe testing

fasthook listen 3000 --save stripe.json --pretty

Forward to your API

fasthook listen 8080 --forward http://localhost:5000/webhook

Mock endpoints in CI

fasthook mock 9000 --spec test-responses.json --quiet

Load testing with replay

fasthook replay events.json --target http://staging.example.com --rate 5 --max-rps 80

---

Testing

fasthook uses pytest with async support.

pytest

Coverage is ~74%.

---

Development

git clone https://github.com/Jermy-tech/fasthook
cd fasthook
pip install -e .
pytest
fasthook listen 3000

---

How It Works (High-Level)

• Built on FastAPI + Uvicorn
• Single catch-all route accepts any HTTP method on any path
• Logs the request, optionally saves, forwards, or mocks responses
• Forwarding uses an async connection pool
• Replay uses timestamped events + async dispatch
• Engine is fully asynchronous for high concurrency

---

License

MIT License — see LICENSE.

---

Author

Built by Jermy Peña

---

Links

• GitHub: https://github.com/Jermy-tech/fasthook
• Issues: https://github.com/Jermy-tech/fasthook/issues
• PyPI: https://pypi.org/project/fasthook/