GitHub X (Twitter) LinkedIn
← All projects
FastAPI & MCP

HookWatch

Webhooks fail silently. HookWatch stores every delivery before acknowledging it, retries what can be retried, moves the rest to a dead letter queue, and exposes the whole lifecycle to AI agents over MCP.

RoleDesign + Build StatusOpen source TypeBackend / infrastructure
HookWatch webhook lifecycle diagram

Overview

Most webhook handlers acknowledge first and process later, so a crash between the two loses the event. HookWatch reverses that order: validate the envelope, verify the signature, write the row, and only then answer 202. Processing happens in a background engine, and a redelivery is recognised by source plus event_id and answered 200 without writing a second row.

POST /webhooks/{source} -> validate -> verify signature -> store -> 202 POST /webhooks/{source} -> already stored -> 200 background engine -> process -> retry / dead letter

Key features

  • Store before ack202 means stored and queued; 200 means that exact event was already safe.
  • Signed deliveriesHMAC-SHA256 per source, with the timestamp inside the signed message and a tolerance window.
  • Retry engineExponential backoff for temporary failures; permanent failures stop early and are classified.
  • Replay and recoveryFailed events stay inspectable and an operator can queue another cycle.
  • MCP serverThe same listings, detail and history over stdio, read only unless an operator key is present.
  • HardeningDatabase backed API keys with roles, request IDs, a body cap, token bucket limits and backup and restore.

How it works

  1. Configure one secret per source in HOOKWATCH_WEBHOOK_SECRETS.
  2. The sender posts to /webhooks/{source} with an X-HookWatch-Signature header.
  3. HookWatch validates, stores and answers 202, or 200 for a duplicate.
  4. The engine processes the row, retries transient failures and moves permanent ones to a dead letter queue.
  5. Inspect /events, replay a failure, or connect an MCP client to read the same data.
uv sync --all-groups uv run uvicorn app.main:app --reload --no-access-log curl -i -X POST http://127.0.0.1:8000/webhooks/github \ -H "Content-Type: application/json" \ -d '{"event_id":"evt_1","event_type":"invoice.paid","occurred_at":"2026-11-07T12:00:00Z","data":{"amount":500}}'

Stack

Python 3.13 FastAPI SQLite MCP HMAC-SHA256 uv pytest

Operations

The service validates its configuration at startup and refuses to run when a required secret is missing. Deliveries are signed per source, API keys carry roles for human and agent access, every request gets an id, bodies are capped and reads and deliveries are rate limited. The database can be backed up, verified and restored from the command line.

Have a project in mind?

Email me
Have a project? Let's talk