convez.ai
MCP Server
reaatech

webhook-relay-mcp

reaatech/webhook-relay-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server that receives webhooks from external services and translates them into agent-consumable events. Signature validation, payload normalization, and tools for subscribe/poll/history.

Instalação

$npx convez-ai reaatech/webhook-relay-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 1 mês
Versão
@reaatech/webhook-relay-webhooks@0.2.0
Issues abertas
10
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

webhook-relay-mcp

License: MIT Node.js MCP SDK

An MCP (Model Context Protocol) server that bridges third-party webhooks into agent workflows. Receives webhooks from Stripe, GitHub, Replicate, Twilio, SendGrid, Slack, Vercel, and generic sources, normalizes them into a consistent event format, and exposes them to MCP clients via subscription-based polling.

Features

  • Multi-source ingestion — Stripe, GitHub, Replicate, Twilio, SendGrid, Slack, Vercel, and Generic
  • Signature validation — HMAC-SHA256/SHA1 verification with constant-time comparison
  • Advanced filtering — DSL with 13 operators ($eq, $gt, $in, $regex, $and, $or, $not, etc.) and dot-notation
  • Event normalization — Source-specific payloads normalized into a unified schema
  • Deduplication — Ingress-level deduplication by webhookId
  • MCP tools — 15 tools: subscribe, unsubscribe, list, poll, history, register, stats, replay, update-source, delete-source, rotate-secret, list-sources, audit-log, source-health, event-types
  • Dual transport — stdio for local agents, HTTP/SSE for remote agents
  • Outbound delivery — Forward events to external URLs with retry and dead-letter queue
  • Prometheus metrics — 7 counters/gauges at /metrics endpoint
  • Admin dashboard — Built-in web UI at /
  • MCP authentication — Optional API key auth for HTTP/SSE connections
  • Audit logging — Persistent audit trail of all operations
  • Source health monitoring — Heartbeat tracking per webhook source
  • SQLite storage — WAL mode, schema migrations, foreign keys
  • Rate limiting — In-memory per-IP rate limiting
  • Event retention — Configurable automatic cleanup
  • Docker support — Multi-stage build with health checks

Quick Start

Requires Node.js >= 20. Building from source additionally requires pnpm >= 10.

Install from npm

The runnable entry point is @reaatech/webhook-relay-mcp, which bundles the HTTP ingestion server, MCP transport, and dashboard:

# Run directly with npx (no install)
ENCRYPTION_KEY=$(openssl rand -hex 32) npx @reaatech/webhook-relay-mcp

# Or install globally — exposes a `webhook-relay-mcp` binary
npm install -g @reaatech/webhook-relay-mcp
ENCRYPTION_KEY=$(openssl rand -hex 32) webhook-relay-mcp

It starts in MCP stdio mode by default (for local agents). Set MCP_TRANSPORT=sse for HTTP/SSE. ENCRYPTION_KEY is required — see Configuration.

Native dependency: the server transitively depends on better-sqlite3, a native addon. Installation downloads a prebuilt binary when one exists for your platform and Node version; otherwise it compiles from source, which requires a C++ toolchain (e.g. build-essential + python3 on Linux, Xcode Command Line Tools on macOS).

Published packages

PackageRole
@reaatech/webhook-relay-mcpRunnable server + CLI (start here)
@reaatech/webhook-relay-toolsMCP server + 15 tools (library)
@reaatech/webhook-relay-webhooksSources, validators, ingestion (library)
@reaatech/webhook-relay-storageSQLite storage + services (library)
@reaatech/webhook-relay-coreTypes, config, crypto, filters (library)

From source (development)

pnpm install
pnpm run build

Configuration

Copy .env.example to .env and adjust as needed:

VariableDefaultDescription
NODE_ENVdevelopmentdevelopment, production, or test
PORT3000HTTP server port
HOST0.0.0.0HTTP server bind address
DATABASE_PATH./data/webhook-relay.dbSQLite database file path
ENCRYPTION_KEY(required)Master key for encrypting webhook secrets at rest
MCP_TRANSPORTstdiostdio for local agents, sse for HTTP/SSE remote access
LOG_LEVELinfotrace, debug, info, warn, error, or fatal
LOG_FORMATjsonjson for structured output, pretty for development
WEBHOOK_BASE_URLhttp://localhost:3000Public-facing base URL for generating webhook endpoint URLs
EVENT_RETENTION_DAYS30Days to retain events before automatic cleanup
ADMIN_API_KEY(optional)API key for securing the /admin/cleanup endpoint
MCP_API_KEY(optional)API key for MCP client authentication
METRICS_ENABLEDtrueEnable Prometheus metrics endpoint
DELIVERY_RETRY_MAX5Max retry attempts for outbound delivery
DELIVERY_RETRY_BACKOFF_MS1000Base backoff time for retries (ms)
SOURCE_HEARTBEAT_MINUTES60Expected heartbeat interval for source health
RATE_LIMIT_WINDOW_MS60000Rate limit sliding window in milliseconds
RATE_LIMIT_MAX_REQUESTS100Max requests per window per IP

Run

MCP stdio mode (default, for local agent use):

pnpm start

HTTP/SSE mode (for remote agents or multi-client setups):

MCP_TRANSPORT=sse pnpm start

Docker

docker compose up --build

MCP Tools

webhooks.subscribe

Create a subscription for event types with optional TTL and filters.

ParameterTypeRequiredDescription
eventTypesstring[]YesEvent type patterns (supports * wildcard, e.g. "payment.*")
filtersobjectNoFilter DSL expression (supports operators: $eq, $gt, $in, $regex, $and, $or, $not, etc.)
ttlnumberNoSubscription TTL in seconds (default: 3600)

webhooks.unsubscribe

Cancel an active subscription by ID.

ParameterTypeRequiredDescription
subscriptionIdstringYesThe subscription ID to cancel

webhooks.list

List subscriptions with optional filtering.

ParameterTypeRequiredDescription
activeOnlybooleanNoReturn only active subscriptions (default: true)
eventTypesstring[]NoFilter by matching event type patterns
limitnumberNoMax results (default: 50, max: 100)

webhooks.poll

Poll for events matching a subscription. Supports blocking mode for long-polling.

ParameterTypeRequiredDescription
subscriptionIdstringNoPoll from a specific subscription
eventTypesstring[]NoEvent type patterns to match
timeoutnumberNoMax wait in seconds (default: 30)
limitnumberNoMax events to return (default: 10)

webhooks.history

Query historical events with cursor-based pagination.

ParameterTypeRequiredDescription
eventTypesstring[]NoFilter by event types
sourcesstring[]NoFilter by source (e.g. "stripe", "github")
startTimestringNoISO 8601 start timestamp
endTimestringNoISO 8601 end timestamp
correlationIdstringNoFilter by correlation ID
limitnumberNoPage size (default: 50, max: 100)
cursorstringNoPagination cursor for next page

webhooks.register

Register a new webhook source configuration.

ParameterTypeRequiredDescription
namestringYesUnique name for this source (e.g. "stripe-production")
sourceTypestringYesOne of: stripe, github, replicate, twilio, sendgrid, slack, vercel, generic
signingSecretstringYesWebhook signing secret (encrypted at rest)
webhookUrlstringNoCustom endpoint URL (auto-generated from WEBHOOK_BASE_URL if omitted)

webhooks.stats

Get aggregate statistics for webhook events.

ParameterTypeRequiredDescription
eventTypesstring[]NoFilter by event types
sourcesstring[]NoFilter by source
startTimestringNoISO 8601 start
endTimestringNoISO 8601 end
groupBystringNoGroup by: type, source, hour, day

webhooks.replay

Replay webhook events to trigger downstream processing.

ParameterTypeRequiredDescription
eventIdstringNoSpecific event ID to replay
startTimestringNoISO 8601 start range
endTimestringNoISO 8601 end range
limitnumberNoMax events (default 10, max 50)

webhooks.update-source

Update an existing webhook source configuration.

ParameterTypeRequiredDescription
namestringYesSource name to update
updatesobjectYesFields: newName, signingSecret, isActive, webhookUrl

webhooks.delete-source

Delete a webhook source configuration.

ParameterTypeRequiredDescription
namestringYesSource name to delete

webhooks.rotate-secret

Rotate a webhook signing secret.

ParameterTypeRequiredDescription
namestringYesSource name
newSecretstringYesNew signing secret (min 8 chars)

webhooks.list-sources

List registered webhook sources.

ParameterTypeRequiredDescription
activeOnlybooleanNoOnly active sources (default: false)
sourceTypestringNoFilter by type

webhooks.audit-log

Query the persistent audit trail of all operations.

ParameterTypeRequiredDescription
actorstringNoFilter by actor
actionstringNoFilter by action
resourceTypestringNoFilter by resource type
startTimestringNoISO 8601 start
endTimestringNoISO 8601 end
limitnumberNoMax results (default 50, max 100)

webhooks.source-health

Check heartbeat status for webhook sources.

ParameterTypeRequiredDescription
namestringNoSpecific source name (all if omitted)

webhooks.event-types

List available event types across registered sources.

ParameterTypeRequiredDescription
sourcestringNoFilter by source

HTTP Endpoints

MethodPathDescription
GET/Admin dashboard web UI
GET/healthBasic health check with version
GET/health/readyReadiness probe
GET/metricsPrometheus metrics endpoint
POST/admin/cleanupTrigger event retention cleanup (requires ADMIN_API_KEY in production)
POST/webhooks/:nameIngest webhook for a registered source (:name = registered source name)
GET/webhooks/:name/verifyWebhook verification handshake (hub challenge)
POST/mcpMCP HTTP/SSE transport endpoint (initialize sessions)
GET/mcpMCP HTTP/SSE transport (streaming GET)
DELETE/mcpMCP HTTP/SSE transport (session termination)

Note: The webhook ingestion path uses the registered source name (e.g. stripe-production), not the source type. This allows multiple configurations per source type (e.g. stripe-test and stripe-production).

Supported Webhook Sources

Stripe

  • Validates Stripe-Signature header (v1 scheme with timestamp tolerance of 5 minutes)
  • Event type mapping: invoice.payment_succeeded → payment.completed, customer.subscription.created → subscription.created, etc.

GitHub

  • Validates X-Hub-Signature-256 header (HMAC-SHA256)
  • Combines X-GitHub-Event header with payload action field for event type

Replicate

  • Optional signature validation via webhook-secret header
  • Derives event type from payload status field

Twilio

  • HMAC-SHA1 validation of the full request URL with sorted form params
  • Separate event type mapping for SMS and Voice status callbacks

SendGrid

  • Validates X-SendGrid-Signature header (HMAC-SHA256), batch event payloads
  • 11 email event type mappings

Slack

  • Custom v0 signature format (HMAC-SHA256 of v0:timestamp:body)
  • Events API payload structure, interactive message support

Vercel

  • Validates x-vercel-signature header (HMAC-SHA1)
  • 9 deployment/project/domain event type mappings

Generic

  • Configurable HMAC algorithm via x-signature-algorithm header
  • Pass-through normalization (preserves original payload structure)

Architecture

                   ┌──────────────────────────────────────────────────────────────┐
                   │                     webhook-relay-mcp                          │
                   │                                                               │
External Services  │  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌─────────────┐ │  ┌───────────┐
┌───────────────┐  │  │ Express  │  │ Signature │  │ SQLite   │  │   Outbound  │ │  │    MCP    │
│ Stripe        │──┼─▶│ HTTP     │─▶│ Validator │─▶│ (WAL)    │─▶│   Delivery  │─┼─▶│  Clients  │
│ GitHub        │──┼─▶│ Server   │  │           │  │          │  │   Engine    │ │  │ (Agents)  │
│ Replicate     │──┼─▶│          │  │ Normalize │  │ Events   │  │  + Retry    │ │  │           │
│ Twilio        │──┼─▶│ /webhooks│  └───────────┘  │ Subscrip │  │  + DLQ      │ │  │ stdio or  │
│ SendGrid      │──┼─▶│ /:name   │                 │ tions    │  └─────────────┘ │  │ HTTP/SSE  │
│ Slack         │──┼─▶│          │  ┌───────────┐  │ Audit    │                  │  │           │
│ Vercel        │──┼─▶│          │  │ Advanced  │  │ Log      │  ┌───────────┐  │  │ 15 tools  │
│ Generic       │──┼─▶│          │  │ Filter    │  │ Sources  │  │ Prometheus│  │  │           │
└───────────────┘  │  └──────────┘  │ DSL ($gt, │  │ Health   │  │ /metrics  │  │  └───────────┘
                   │               │ $in, ...)  │  │          │  └───────────┘  │
                   │               └───────────┘  │          │                 │
                   │                              └──────────┘                 │
                   │                                    │                      │
                   │                    ┌───────────────┘                      │
                   │                    ▼                                      │
                   │              ┌───────────┐  ┌───────────┐               │
                   │              │   Admin   │  │    MCP    │               │
                   │              │ Dashboard │  │   Auth    │               │
                   │              │    (/)    │  │ (API Key) │               │
                   │              └───────────┘  └───────────┘               │
                   └──────────────────────────────────────────────────────────────┘

Data flow: External webhook → signature validation → payload normalization → deduplication check → SQLite storage → notify matching poll waiters → MCP clients receive events. Outbound delivery forwards events to external URLs with retry and dead-letter queue.

Development

# Start dev server with hot reload
pnpm run dev

# Run all tests
pnpm run test

# Run tests in watch mode
pnpm run test:watch

# Run tests with coverage report
pnpm run test:coverage

# Run all quality checks
pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build

# Format code
pnpm run format

# Check formatting (CI)
pnpm run format:check

Project Structure

packages/
├── core/                      # Shared types, config, crypto, validation, filters, metrics
├── storage/                   # SQLite, repositories, migrations, services
│   ├── repositories/          # Events, Subscriptions, Sources, Audit
│   └── services/              # Cleanup, Delivery, Audit, SourceHealth, PollWaiter
├── webhooks/                  # Ingest, validators, source handlers
│   ├── sources/               # stripe, github, replicate, twilio, sendgrid, slack, vercel, generic
│   └── validators/            # HMAC, Stripe, GitHub, Slack, Twilio
├── mcp/                       # MCP server, tool implementations (15 tools)
│   └── tools/
└── server/                    # Express HTTP server, middleware, dashboard
    └── middleware/             # RateLimit, RawBody, MCPAuth

Security

  • Signature validation: All webhooks validated with crypto.timingSafeEqual for constant-time comparison
  • Secrets at rest: Signing secrets encrypted with AES-256-GCM
  • MCP authentication: Optional API key auth for HTTP/SSE connections via X-API-Key or Authorization: Bearer
  • Audit logging: Persistent audit trail of all MCP tool operations in the audit_log table
  • Rate limiting: In-memory per-IP sliding window rate limiting on all webhook ingestion endpoints
  • Input validation: All inputs validated with Zod schemas; SQL injection prevented via parameterized queries
  • Deduplication: Webhook-level deduplication by webhookId prevents replay attacks
  • Admin auth: ADMIN_API_KEY secures the /admin/cleanup endpoint in production

Limitations

  • Single-instance polling: webhooks.poll blocking mode uses in-memory waiters per process. In a horizontally-scaled deployment, a webhook arriving on one instance will not wake a poller on another instance. Use non-blocking polling (timeout: 0) for multi-instance deployments, or deploy as a single instance.
  • In-memory rate limiting: Rate limits are not shared across instances behind a load balancer. For multi-instance deployments, use an external rate limiting solution.
  • SQLite scalability: SQLite with WAL mode supports moderate concurrency but is not designed for high-throughput distributed workloads. Consider migrating to PostgreSQL for large-scale production deployments.

License

MIT — see LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados