Agent Webhook

Webhook management, delivery, and relay service for autonomous agents — MCP server + CLI

Built for the agentic economy — by Nyx Builds.

Features

Endpoint Management — Register, configure, and organize webhook endpoints with custom headers, secrets, and tags
Reliable Delivery — Send webhooks with automatic retries, exponential backoff, and HMAC signature generation
Circuit Breaker — Automatic failure detection per endpoint: stops wasting resources on failing targets, tests recovery with half-open state
Batch Delivery — Send the same payload to multiple endpoints at once
Event Subscriptions — Subscribe endpoints to specific event types and broadcast to subscribers
Delivery Cancellation — Cancel pending or retrying deliveries
Recurring Schedules — Set up periodic webhook delivery (cron-like intervals) for heartbeats, polling, and check-ins. Configurable interval (seconds/minutes/hours/days), max-run limits, pause/resume, and auto-deactivation on exhaustion
Bulk Endpoint Operations — Mass pause, resume, disable, or delete endpoints by ID list or tag — essential for fleet management
Dry-Run Simulation — Preview exactly what would be sent (URL, method, headers, HMAC signature, transformed payload, retry policy) without making any HTTP request
Dead Letter Queue — Permanently failed deliveries are captured for inspection and replay
Payload Transforms — Rename, filter, or template webhook payloads before delivery
Relay Filters — Conditional forwarding rules based on headers and payload fields (equals, regex, numeric, list operators)
Incoming Signature Verification — Verify HMAC signatures from GitHub, Stripe, Slack, Shopify, or generic providers with replay-attack prevention
Alert Rules — Proactive alerting on circuit breaker opens, DLQ thresholds, endpoint failure rates, endpoint downs, and stalled deliveries — with webhook, log, and callback notification channels
Data Retention — Automatic cleanup of old deliveries, event logs, dead-letter entries, and incoming webhooks with configurable policies and dry-run preview
API Key Authentication — SHA-256 hashed API keys with scopes, expiration, and revocation for securing the REST API
Rate Limiting — Per-endpoint rate limits with burst capacity
Prometheus Metrics — Delivery counts, durations, rate-limit and dead-letter counters exposed via /metrics
Import / Export — Portable config export (secrets excluded by default) with skip/overwrite/rename conflict resolution
Health Checks — Test endpoint connectivity with ping payloads
Event Audit Log — Timestamped log of all webhook events for audit trails
Delivery Tracking — Full execution history with status codes, response bodies, and timing
Relay Server — Forward incoming webhooks to registered endpoints using path-based routing rules
Webhook Templates — Pre-configured endpoint templates for common services (Slack, Discord, generic JSON, etc.)
Analytics Dashboard — Endpoint health scoring, duration stats, failure patterns, and retry analytics
Background Worker Pool — Async worker pool for processing deliveries, schedules, and retries in the background
REST API — Optional FastAPI server for HTTP access to all operations
Service Layer — Clean business logic API on top of store and engine
MCP Server — 70 tools for full webhook management from any MCP-compatible agent
Rich CLI — Beautiful terminal interface with tables, colors, and filtering
SQLite Backend — Default persistent storage with JSON-to-SQLite migration; JSON file backend also supported

Quick Start

pip install agent-webhook

# Register a webhook endpoint
agent-webhook endpoint add "Slack Notifications" https://hooks.slack.com/services/XXX --tag "notifications"

# Send a webhook
agent-webhook send <endpoint-id> '{"text": "Hello from agent-webhook!"}'

# List endpoints
agent-webhook endpoint list

# Check delivery stats
agent-webhook stats

# Subscribe an endpoint to events
agent-webhook subscription add <endpoint-id> --event-type order.created --event-type order.updated

CLI Reference

Endpoint Management

# Add an endpoint
agent-webhook endpoint add <name> <url> [options]
  --method, -m        HTTP method (POST, PUT, PATCH, GET, DELETE) [default: POST]
  --header, -H        Custom header in 'Name: Value' format (repeatable)
  --tag, -t           Tag for filtering (repeatable)
  --secret            HMAC signing secret
  --timeout           Request timeout in seconds [default: 30]
  --description, -d   Description
  --max-retries       Max retry attempts [default: 3]

# List endpoints
agent-webhook endpoint list [--status active|paused|disabled] [--tag TAG]

# Show endpoint details (including subscriptions)
agent-webhook endpoint show <endpoint-id>

# Pause/Resume/Delete
agent-webhook endpoint pause <endpoint-id>
agent-webhook endpoint resume <endpoint-id>
agent-webhook endpoint delete <endpoint-id>

Sending Webhooks

# Send a payload
agent-webhook send <endpoint-id> '<json-payload>'
agent-webhook send <endpoint-id> - < input.json  # from stdin

  --event-type, -e   Event type tag
  --header, -H       Extra headers in 'Name: Value' format

# Batch send to multiple endpoints
agent-webhook batch-send '<json-payload>' --endpoint <id1> --endpoint <id2>
  --event-type, -t   Event type tag
  --header, -H       Extra headers

Delivery Tracking

# List deliveries
agent-webhook delivery list [--endpoint ID] [--status STATUS] [--event-type TYPE] [--limit N]

# Show delivery details with attempts
agent-webhook delivery show <delivery-id>

# Cancel a pending or retrying delivery
agent-webhook delivery cancel <delivery-id>

Event Subscriptions

# Subscribe an endpoint to event types
agent-webhook subscription add <endpoint-id> --event-type order.created --event-type order.updated

# List subscriptions
agent-webhook subscription list [--endpoint ID]

# Delete a subscription
agent-webhook subscription delete <subscription-id>

Health Check

# Test endpoint connectivity
agent-webhook health-check <endpoint-id>

Event Audit Log

# View event log
agent-webhook event-log [--event-type TYPE] [--endpoint ID] [--limit N]

Relay Rules

# Add a relay rule (forward incoming webhooks to endpoints)
agent-webhook relay add <name> <path-pattern> --target <endpoint-id> [--tag TAG]

# List rules
agent-webhook relay list

# Delete a rule
agent-webhook relay delete <rule-id>

Incoming Webhooks

# List received webhooks
agent-webhook incoming list [--path PATH] [--limit N]

Statistics

# Stats for all endpoints
agent-webhook stats

# Stats for a specific endpoint
agent-webhook stats <endpoint-id>

Process Pending

# Process all pending/ready deliveries
agent-webhook process-pending

MCP Server

Run the MCP server for agent integration:

agent-webhook-mcp

Or configure in your MCP client:

{
  "mcpServers": {
    "agent-webhook": {
      "command": "agent-webhook-mcp",
      "args": []
    }
  }
}

MCP Tools (70)

Tool	Description
`endpoint_add`	Register a new webhook endpoint
`endpoint_list`	List all webhook endpoints
`endpoint_get`	Get endpoint details
`endpoint_update`	Update an endpoint
`endpoint_delete`	Delete an endpoint
`endpoint_from_template`	Create endpoint from a pre-configured template
`webhook_send`	Send a webhook delivery
`webhook_batch_send`	Send a payload to multiple endpoints
`webhook_schedule`	Schedule a delivery for a future time
`delivery_list`	List deliveries
`delivery_get`	Get delivery details with attempts
`delivery_retry`	Retry a failed delivery
`delivery_cancel`	Cancel a pending/retrying delivery
`delivery_simulate`	Dry-run preview of what would be sent (no HTTP)
`process_pending`	Process all pending deliveries
`health_check`	Test endpoint connectivity
`stats`	Get delivery statistics
`subscription_add`	Subscribe an endpoint to event types
`subscription_list`	List event subscriptions
`subscription_delete`	Delete an event subscription
`send_to_subscribers`	Send to all endpoints subscribed to an event type
`relay_add`	Add a relay rule
`relay_list`	List relay rules
`relay_delete`	Delete a relay rule
`relay_update`	Update a relay rule (name, path, targets, active, tags)
`relay_set_filter`	Set conditional filter rules on a relay rule
`relay_validate_filter`	Validate relay filter rules before applying
`incoming_list`	List incoming webhooks
`incoming_receive`	Receive & relay an incoming webhook
`event_log`	List event audit log entries
`transform_create`	Create a payload transform (field_map / filter / template)
`transform_list`	List all payload transforms
`transform_get`	Get transform details
`transform_update`	Update a payload transform
`transform_delete`	Delete a payload transform
`dead_letter_list`	List entries in the dead letter queue
`dead_letter_get`	Get dead letter entry details
`dead_letter_replay`	Replay a dead letter entry (new delivery)
`dead_letter_batch_replay`	Replay all unreplayed dead letter entries
`dead_letter_delete`	Delete a dead letter entry
`rate_limit_status`	Get rate limit status for an endpoint
`circuit_breaker_state`	Get circuit breaker state for an endpoint
`circuit_breaker_all`	Get circuit breaker states for all endpoints
`circuit_breaker_reset`	Force-close an endpoint's circuit breaker
`metrics`	Get delivery metrics (JSON or Prometheus format)
`verify_signature`	Verify an incoming webhook HMAC signature
`detect_provider`	Auto-detect webhook provider from headers
`generate_signature`	Generate a test HMAC signature for a payload
`export_config`	Export configuration to portable format
`import_config`	Import configuration with conflict strategies
`migrate_json_to_sqlite`	Migrate JSON store to SQLite backend
`recurring_schedule_create`	Create a recurring delivery schedule
`recurring_schedule_list`	List recurring schedules
`recurring_schedule_pause`	Pause a recurring schedule
`recurring_schedule_resume`	Resume a paused schedule
`recurring_schedule_delete`	Delete a recurring schedule
`bulk_endpoint_pause`	Bulk pause endpoints by IDs or tag
`bulk_endpoint_resume`	Bulk resume endpoints by IDs or tag
`bulk_endpoint_disable`	Bulk disable endpoints by IDs or tag
`bulk_endpoint_delete`	Bulk delete endpoints by IDs or tag
`template_list`	List available webhook templates
`template_get`	Get template details
`analytics_overview`	Analytics dashboard: global health, top endpoints
`analytics_endpoint`	Per-endpoint analytics: health score, duration stats
`analytics_retry`	Retry analytics: success rates, avg attempts
`alert_summary`	Alert state summary (rules, firing, resolved)
`alert_evaluate`	Evaluate alert rules and get fired events
`retention_estimate`	Preview retention cleanup impact (dry run)
`retention_cleanup`	Run data retention cleanup
`apikey_generate`	Generate a new API key with optional scopes/expiry

Python API

Using the Service Layer

from agent_webhook.service import WebhookService

# Setup
service = WebhookService(store_path="webhooks.json")

# Create an endpoint
endpoint = service.create_endpoint(
    name="My Service",
    url="https://api.example.com/webhook",
    secret="shared-secret",
    tags=["production"],
)

# Subscribe to events
service.add_subscription(endpoint.id, event_types=["order.created", "order.updated"])

# Send a webhook
import asyncio
result = asyncio.run(service.send_webhook(
    endpoint_id=endpoint.id,
    payload={"event": "order.created", "order_id": "12345"},
    event_type="order.created",
))
print(f"Status: {result.status}")

# Batch send to multiple endpoints
results = asyncio.run(service.batch_send(
    endpoint_ids=[endpoint.id, other_endpoint.id],
    payload={"broadcast": True, "message": "Hello all!"},
))

# Send to all subscribers of an event type
results = asyncio.run(service.send_to_subscribers(
    event_type="order.created",
    payload={"order_id": "12345"},
))

# Health check
health = asyncio.run(service.health_check(endpoint.id))
print(f"Healthy: {health['healthy']}")

# View audit log
entries = service.list_event_log(event_type="delivery.success", limit=10)

# Cancel a delivery
service.cancel_delivery(delivery_id)

# Close
asyncio.run(service.close())

Using the Engine Directly

from agent_webhook.store import WebhookStore
from agent_webhook.engine import DeliveryEngine
from agent_webhook.models import WebhookEndpoint

# Setup
store = WebhookStore("webhooks.json")
engine = DeliveryEngine(store)

# Register endpoint
endpoint = WebhookEndpoint(
    name="My Service",
    url="https://api.example.com/webhook",
    secret="shared-secret",
    tags=["production"],
)
store.add_endpoint(endpoint)

# Send a webhook
import asyncio
result = asyncio.run(engine.send(
    endpoint_id=endpoint.id,
    payload={"event": "order.created", "order_id": "12345"},
    event_type="order.created",
))
print(f"Status: {result.status}")

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   CLI / MCP  │────▶│   Service    │────▶│   Endpoints  │
│   Interface  │     │    Layer     │     │  (external)  │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                     ┌──────┴──────┐
                     │             │
                     ▼             ▼
              ┌──────────────┐  ┌──────────────┐
              │    Engine    │  │    Store     │
              │  (delivery)  │  │  (persist)   │
              └──────────────┘  └──────────────┘
                     │
           ┌─────────┼─────────┐
           │         │         │
           ▼         ▼         ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │  Relay   │ │ Incoming │ │  Event   │
    │  Rules   │ │ Webhooks │ │   Log    │
    └──────────┘ └──────────┘ └──────────┘

Key Concepts

Endpoint — A registered webhook target with URL, method, headers, secret, and retry policy
Delivery — An attempt to send a payload to an endpoint, with full attempt history
DeliveryAttempt — A single HTTP request, tracking status code, response, and timing
EventSubscription — Links an endpoint to specific event types for targeted delivery
RelayRule — Routes incoming webhooks by path pattern to one or more endpoints
IncomingWebhook — A webhook received by the relay, with forwarding tracking
EventLogEntry — An audit trail entry recording webhook system events

Retry Logic

Failed deliveries are automatically retried with exponential backoff:

Configurable max retries (default: 3)
Initial delay: 1s, doubles each attempt (2s, 4s, 8s...)
Max delay cap: 300s
Retry on status codes: 408, 429, 500, 502, 503, 504
Connection errors trigger retry
Non-retryable errors (4xx) are abandoned

HMAC Signatures

When a secret is configured on an endpoint, all deliveries include an X-Webhook-Signature header:

X-Webhook-Signature: sha256=<hex-digest>

Receivers can verify the signature to authenticate the webhook source.

Event Subscriptions

Endpoints can subscribe to specific event types. When you broadcast an event using send_to_subscribers, all active endpoints subscribed to that event type receive the payload. This enables pub/sub patterns:

# Subscribe
service.add_subscription(endpoint_id, event_types=["order.created"])

# Broadcast to all subscribers
results = asyncio.run(service.send_to_subscribers(
    event_type="order.created",
    payload={"order_id": "12345"},
))

Event Audit Log

All significant webhook events are recorded in the audit log with timestamps, event types, and details. The log is capped at 1000 entries to prevent unbounded growth:

entries = service.list_event_log(event_type="delivery.success", limit=10)
for entry in entries:
    print(f"[{entry.timestamp}] {entry.event_type}: {entry.details}")

Circuit Breaker

Each endpoint can have a circuit breaker that automatically stops delivery after consecutive failures, giving the downstream service time to recover:

CLOSED — Normal operation. Failures are counted.
OPEN — All deliveries blocked for a cooldown period (default 60s).
HALF_OPEN — Trial deliveries allowed. After enough successes the circuit closes; any failure re-opens it.

# Configure via endpoint creation
endpoint = WebhookEndpoint(
    name="Flaky Service",
    url="https://api.example.com/webhook",
    circuit_breaker_enabled=True,
    circuit_breaker_config={
        "failure_threshold": 5,      # open after 5 consecutive failures
        "recovery_timeout": 60.0,    # wait 60s before half-open
        "half_open_max_calls": 3,    # allow 3 trial deliveries
        "success_threshold": 2,      # 2 successes to close
    },
)

# Check state via CLI
# agent-webhook circuit-breaker state <endpoint-id>
# agent-webhook circuit-breaker reset <endpoint-id>

Incoming Signature Verification

Relay rules can verify HMAC signatures on incoming webhooks to prevent spoofing and replay attacks:

# Relay rule with GitHub signature verification
rule = RelayRule(
    name="GitHub Webhooks",
    path_pattern="/github/*",
    target_endpoint_ids=[endpoint.id],
    verify_signature=True,
    verify_secret="your-webhook-secret",
    verify_provider="github",  # or: stripe, slack, shopify, generic
    verify_tolerance_seconds=300,
)

Supported providers auto-extract the signature and timestamp from the correct headers and use the correct hashing scheme. Use the detect_provider MCP tool to auto-identify a provider from request headers.

REST API

Run the REST API server (requires pip install agent-webhook[rest]):

# Default: SQLite backend on port 8000
agent-webhook serve --host 0.0.0.0 --port 8000

# Key endpoints
GET  /health                    # health check
GET  /metrics                   # JSON metrics
GET  /metrics/prometheus        # Prometheus scrape format
GET  /api/endpoints             # list endpoints
POST /api/endpoints             # create endpoint
POST /api/deliveries            # send a delivery
GET  /api/deliveries            # list deliveries
POST /webhooks/{path:path}      # relay receiver (matches relay rules)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run specific test
pytest tests/test_service.py -v

Changelog

v0.7.0

Alert Rules — Proactive alerting system with 5 condition types (circuit_open, dlq_threshold, endpoint_failure_rate, endpoint_down, delivery_stalled), cooldown periods to prevent alert fatigue, and 3 notification channels (LogChannel for audit log, WebhookChannel for forwarding, CallbackChannel for custom handlers). Preset default rules and custom rule creation. REST API: /alerts/summary, /alerts/evaluate. CLI: alert list-presets, alert summary, alert evaluate. MCP tools: alert_summary, alert_evaluate.
Data Retention — Automatic cleanup of old deliveries, event log entries, dead-letter entries, and incoming webhooks. Configurable per-type retention windows, keep-failed option, batch-size limits, dry-run preview estimates. REST API: /retention/estimate, /retention/cleanup. CLI: retention show, retention run. MCP tools: retention_estimate, retention_cleanup.
API Key Authentication — SHA-256 hashed API keys with scopes (* wildcard or specific), expiration timestamps, and revocation. FastAPI middleware for X-API-Key, Authorization: Bearer, and ?api_key= query param. REST API: /apikeys/generate. CLI: apikey generate. MCP tool: apikey_generate.
Bug Fixes — Fixed AlertRule.id uniqueness (UUID instead of name-derived slug), fixed AlertRule default channels (auto-attach LogChannel), fixed APIKey.is_valid as property, fixed create_app() to accept service= parameter, fixed DLQ cleanup with 0-day retention, aligned __init__.py version with pyproject.toml.
Documentation — Updated README with 70 MCP tools (was 46), added v0.7.0 features and changelog.
Tests — Fixed all 14 v0.7.0 test failures + 8 errors. 612 tests passing.

v0.6.0

Recurring Schedules — Periodic webhook delivery (cron-like intervals: seconds/minutes/hours/days) with configurable max-runs, pause/resume, start_at delay, auto-deactivation on exhaustion, and automatic worker integration
Bulk Endpoint Operations — Mass pause, resume, disable, and delete endpoints by ID list or tag — essential for fleet management
Dry-Run Simulation — Preview exactly what would be sent (URL, method, headers, HMAC signature, transformed payload, retry policy, rate limit) without making any HTTP request
CLI — New command groups: schedule (create/list/pause/resume/delete/show/fire), bulk (pause/resume/disable/delete), and simulate
MCP Server — Expanded from 42 to 46 tools (added recurring_schedule_, bulk_, simulate_delivery)
Tests — Expanded from 524 to 545 tests across 15 test files

v0.5.0

Circuit Breaker — Per-endpoint automatic failure detection (CLOSED → OPEN → HALF_OPEN), configurable threshold/recovery, force-reset via CLI/MCP
Incoming Signature Verification — Verify HMAC signatures from GitHub, Stripe, Slack, Shopify, and generic providers with timestamp-based replay-attack prevention
Relay Filters — Conditional forwarding rules based on header and payload fields with operators (equals, not_equals, contains, starts_with, ends_with, regex, exists, eq/ne/gt/gte/lt/lte, in/not_in) and all/any/none logic
Import / Export — Portable config export (secrets excluded by default) with skip/overwrite/rename conflict strategies on import
Metrics — Delivery counters, duration histogram, rate-limit and dead-letter metrics exposed via CLI and REST /metrics (Prometheus format supported)
REST API additions — /metrics and /metrics/prometheus endpoints
Bug Fixes — Dead letter batch replay MCP bug, WebhookService store detection for SQLite
Tests — Expanded to 524 tests across 14 test files

v0.4.0

Dead Letter Queue — Permanently failed deliveries captured for inspection and replay
Payload Transforms — field_map (rename), filter (include/exclude), template (string interpolation)
Rate Limiting — Per-endpoint limits with configurable period and burst
Prometheus Metrics — Delivery counters and duration histograms
SQLite Backend — Persistent storage with JSON-to-SQLite migration tool
REST API — Full FastAPI server with 24 integration tests
MCP Server — Expanded from 24 to 36 tools
Tests — 290 tests

v0.3.0

Transforms, Rate Limiting, Dead Letter Queue, SQLite backend, Prometheus metrics, REST API

v0.2.0

Event Subscriptions — Subscribe endpoints to event types, broadcast to subscribers
Batch Delivery — Send the same payload to multiple endpoints at once
Delivery Cancellation — Cancel pending or retrying deliveries
Health Checks — Test endpoint connectivity with ping payloads
Event Audit Log — Timestamped log of all webhook events (capped at 1000)
Service Layer — Clean business logic API (WebhookService)
MCP Server — Expanded from 17 to 24 tools
CLI — New commands: subscription, batch-send, health-check, event-log, delivery cancel
Tests — 209 tests (up from ~85), added test_service.py and test_cli.py
Bug Fix — Fixed asyncio event loop issues in CLI commands

v0.1.0

Initial release with endpoint management, delivery, relay, MCP server, and CLI

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
src/agent_webhook		src/agent_webhook
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
check_sqlite.py		check_sqlite.py
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Agent Webhook

Features

Quick Start

CLI Reference

Endpoint Management

Sending Webhooks

Delivery Tracking

Event Subscriptions

Health Check

Event Audit Log

Relay Rules

Incoming Webhooks

Statistics

Process Pending

MCP Server

MCP Tools (70)

Python API

Using the Service Layer

Using the Engine Directly

Architecture

Key Concepts

Retry Logic

HMAC Signatures

Event Subscriptions

Event Audit Log

Circuit Breaker

Incoming Signature Verification

REST API

Development

Changelog

v0.7.0

v0.6.0

v0.5.0

v0.4.0

v0.3.0

v0.2.0

v0.1.0

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages