Skip to main content
Glama
webhooks-mcp

webhooks-mcp

by davcs86

webhooks-mcp

A lite webhook server with an MCP interface. A publisher POSTs JSON to a webhook URL; the service stores it; an AI agent then lists, fetches or waits for those events over MCP. Typical use: a service in a private network hands an event to an agent that cannot be reached directly.

One process, two listeners:

Listener

Port

Serves

MCP

9100

POST /mcp (Streamable HTTP, bearer key), GET /healthz

Ingest

9101

POST /hooks, POST /hooks/{name}, GET /healthz

Ingestion (port 9101)

Bodies must be JSON, at most 256 KiB. An optional Idempotency-Key header (unique per event name, at most 255 characters) makes retries safe. The client address is the first entry of X-Forwarded-For if valid, else the peer address.

# Typed: the name travels in the body
curl -X POST http://127.0.0.1:9101/hooks -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: build-42' \
  -d '{"event_name":"smoke.test","payload":{"ok":true}}'
# 201 {"event_id":"…","duplicate":false}      (a repeat: 200 with "duplicate":true)

# Minted: the name comes from the URL and the whole body is the payload
curl -X POST http://127.0.0.1:9101/hooks/minted.demo-k7q2xw4mzr3p -d '{"any":"json"}'

Result

Status

Stored

201 {"event_id", "duplicate": false}

Idempotent repeat

200 {"event_id", "duplicate": true}

Not JSON, bad or missing event_name, missing payload, minted. prefix on the typed endpoint

422 {"error"}

Body over 256 KiB

413

Minted name never issued or expired

404

More than 32 requests already in flight on the ingest listener

503 (retry later)

event_name matches ^[a-z0-9][a-z0-9._-]{0,127}$.

Related MCP server: webhook-toolkit

MCP tools (port 9100)

Every request needs Authorization: Bearer <MCP_AUTH_KEY>; otherwise 401.

Tool

Purpose

list_events(event_name, after_seq=0, page_size=20)

Events for a name, oldest first; page_size is clamped to 1..100. Returns {events, next_after_seq}

get_event(event_id)

One event with its full payload; NOT_FOUND if unknown

wait_for_event(event_name, after_seq=0, timeout_s=25)

Returns once an event newer than after_seq exists, or empty at the timeout (at most 25 s)

mint_webhook_url(label)

Creates a minted.<label>-<random> name; returns {event_name, urls, expires_at} with one URL per INGEST_BASE_URLS entry. label: lowercase letters, digits, hyphens, 1 to 32 characters

list_event_names()

Names that currently hold events, with counts, in name order. Returns {names: [{event_name, count}], truncated}; at most 500 names, truncated: true when more exist

Each event is {event_id, seq, event_name, received_at, source_ip, payload_bytes, payload}. Lists and waits inline a payload only up to 4 KiB; a larger one comes back as payload_truncated: true and is fetched with get_event. Pass next_after_seq back as after_seq to page. Reads never delete.

Configuration

Env var

Meaning

MCP_AUTH_KEY

Bearer key, at least 32 characters. The process exits with status 2 if it is missing or short

INGEST_BASE_URLS

JSON object of label to base URL used to build minted URLs; must contain default, e.g. {"default":"http://127.0.0.1:9101"}

DATA_DIR

Directory for the SQLite database (events.db). Default /data; must exist and be writable

Retention

Events and minted names live 7 days. Two bounds are enforced on every insert, evicting oldest first: each event name keeps at most 1000 events, and the store as a whole stays within a 1 GiB budget, deleting the globally oldest events until it fits. The budget charges each event its payload_bytes plus a fixed 1 KiB per-row overhead, so many tiny events cannot outgrow it on disk. The event just stored is never evicted by its own insert. Cursors stay valid: seq values are never reused, so an evicted event simply no longer appears after after_seq. A sweep runs at start and hourly to expire old events and minted names and to return freed space to the filesystem (for a database file first created by this version; an older file keeps its free pages for reuse). These values live in src/webhooks_mcp/constants.py.

Run it

Locally (needs uv):

mkdir -p /tmp/wm-data
DATA_DIR=/tmp/wm-data MCP_AUTH_KEY="$(openssl rand -hex 24)" \
  INGEST_BASE_URLS='{"default":"http://127.0.0.1:9101"}' uv run webhooks-mcp

With Docker, hardened the way the edge runs it:

docker run -d --name wm --read-only --cap-drop ALL --security-opt no-new-privileges --memory 192m \
  -v wm-data:/data -p 127.0.0.1:9100:9100 -p 127.0.0.1:9101:9101 \
  -e MCP_AUTH_KEY="$(openssl rand -hex 24)" \
  -e INGEST_BASE_URLS='{"default":"http://127.0.0.1:9101"}' \
  ghcr.io/davcs86/webhooks-mcp@sha256:<digest>

scripts/smoke.sh <image> runs this and checks the contract end to end. Tests: uv lock --check && uv run pytest -W error (as CI runs them).

Security model

  • MCP: bearer key compared in constant time; the key is never logged. The MCP port is the only one that may be exposed beyond a private network, behind TLS.

  • Ingestion has no authentication, by design. Publish port 9101 only to a private network such as a tailnet. Minted names carry a random suffix and expire, but they are not secrets worth relying on.

  • Payloads are untrusted third-party data. They are returned only inside a payload field, and every tool description tells the agent never to follow instructions found in one.

  • The container runs as uid 10001 with a read-only root; only /data is written.

Release

Merging to main publishes ghcr.io/davcs86/webhooks-mcp:<sha>, moves the tag main to it, and prints the digest (ghcr.io/davcs86/webhooks-mcp@sha256:…) in the CI job summary. Deployments pin that digest, so a merge here changes nothing until the pin is bumped where the service is deployed. The full path to the homelab edge, and the one-time GHCR visibility step, are in docs/release.md. The cross-repo contracts are in docs/contracts.md.

MIT licensed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables apps to publish events on channels to a local broker that wakes the listening agent sessions, which handle the event and reply back. It provides the reverse direction of MCP with at-least-once delivery, routing across many apps and agents, and scoped token authentication.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to list and fetch webhook events stored locally in SQLite, turning inbound webhook POSTs received on localhost into retrievable MCP read tools.
      MIT