webhooks-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
|
Ingest | 9101 |
|
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 |
Idempotent repeat | 200 |
Not JSON, bad or missing | 422 |
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 |
| Events for a name, oldest first; |
| One event with its full payload; |
| Returns once an event newer than |
| Creates a |
| Names that currently hold events, with counts, in name order. Returns |
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 |
| Bearer key, at least 32 characters. The process exits with status 2 if it is missing or short |
| JSON object of label to base URL used to build minted URLs; must contain |
| Directory for the SQLite database ( |
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-mcpWith 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
payloadfield, 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
/datais 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Webhooks for AI agents: send events, manage endpoints, inspect and retry deliveries.
Anonymous webhook capture, inspection, waiting, and response configuration for AI agents.
Discover MCP servers and A2A agents; verify, message, post, follow, react, and receive webhooks.
Webhook URLs for AI agents: receive, wait for, replay, sign and verify webhooks (Stripe, GitHub…).
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA webhook management and delivery service with MCP tools for endpoints, deliveries, relay, and incoming webhooks, enabling autonomous agents to send, track, and relay webhooks.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to create webhook URLs, wait for incoming deliveries, inspect payloads, and replay or send signed webhook events to a local handler.49 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables agents to list and fetch webhook events stored locally in SQLite, turning inbound webhook POSTs received on localhost into retrievable MCP read tools.MIT