Openhook

Openhook

An event inbox for AI agents. Create a public URL, wait for a callback, inspect what arrived, and continue the task.

Openhook operates its own HTTP, SMTP, and authoritative DNS capture servers. Events live in its SQLite database. No external webhook service is involved.

Try it or host it

Create a free inbox without an account, or connect your agent. Optional hosted Pro provides persistent inboxes and account recovery; see the current availability and plans. Self-hosting remains MIT licensed with no Openhook account or subscription.

Practical recipes: local forwarding, GitHub push callbacks, and Stripe test callbacks.

First callback in under a minute

With Python 3 installed, clone the repository and run the disposable example:

git clone https://github.com/openhook-dev/openhook-inbox.git
cd openhook-inbox
python3 examples/first_callback.py

It creates a free inbox on openhook.dev, sends a real callback, verifies the original bytes, then deletes its inbox and payload. The private token stays in memory. No account, API key, or Python dependencies are needed for this example. Minimal operational activity metadata remains after deletion.

Install the agent skill

For Codex, Claude Code, and other compatible Agent Skills clients:

npx skills add openhook-dev/openhook-inbox --skill openhook

The skill setup and permissions explain MCP connection, REST fallback, local forwarding, and handling private inbox tokens. Installing the skill does not install or start the server.

Install for Gemini CLI

gemini extensions install https://github.com/openhook-dev/openhook-inbox --ref main

Restart Gemini CLI after installation. The extension connects to the hosted https://openhook.dev/mcp endpoint; it does not start a local capture server. It also includes the Openhook agent skill for callback testing workflows. No Openhook account or API key is needed to connect or create a disposable inbox. Keep the private token returned by create_webhook secret: reading and deleting that inbox requires the token as a tool argument. Persistent hosted inboxes require a separate Openhook account key.

Ask the agent to create a disposable inbox, then give its public URL to the system you are testing. Capturing a callback proves it arrived at Openhook; check your application's state separately to confirm that its handler worked.

Remove the extension with gemini extensions uninstall openhook-inbox.

Connect OpenCode

Merge this entry into your project's opencode.json (preserve existing settings):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openhook": {
      "type": "remote",
      "url": "https://openhook.dev/mcp",
      "enabled": true
    }
  }
}

Run opencode mcp list from that project to check the connection, then ask OpenCode to create a disposable inbox and inspect a synthetic callback. No Openhook account is needed for a disposable inbox. Keep its private token out of the config and committed files; only give the public callback URL to senders. Delete the test inbox after checking its contents. Receipt at Openhook does not prove that your application's handler processed the event.

This configuration connected successfully with OpenCode 1.19.1. That verifies the MCP connection, not a model-driven end-to-end workflow. See the OpenCode MCP documentation for client configuration. To disconnect, remove the mcp.openhook entry or set its enabled value to false.

Run it

From the checkout, install uv and start your own server:

uv sync
uv run openhook --http

Open http://127.0.0.1:8788/app. The website, capture API, and Streamable HTTP MCP endpoint share one service and one durable store.

Connect an MCP client to http://127.0.0.1:8788/mcp, or use uv run openhook for stdio. A local stdio process shares the same database with a running HTTP process when both use the same OPENHOOK_DATABASE. The HTTP process must be running to receive HTTP callbacks. Check the same loop against your server with python3 examples/first_callback.py --url http://127.0.0.1:8788. External providers need a publicly reachable origin; the localhost example only proves your local server works.

GitHub releases provide versioned source and Python distributions when available. The openhook-mcp package is not currently published on PyPI; use the source checkout or a release artifact rather than assuming a package-index install works.

Agent workflow

1. Call create_webhook. Save the private ohk_ management token.
2. Give the returned public HTTP URL, email address, or DNS name to the sender.
3. Call wait_for_request with the management token.
4. Inspect the event and act. Reconnect using the returned next_since cursor.

Public capture addresses cannot read or delete events. Rotate a compromised management token with rotate_webhook_token. Rotation preserves public addresses.

Anonymous inboxes expire within seven days. Each accepts up to 1000 retained events. When full, capture returns a capacity error instead of evicting accepted events. Individual events are limited to 1 MB. Email and DNS addresses are returned only when their listeners are configured.

Native tools

29 tools cover inbox creation, response configuration, token rotation, event inspection, literal search, notes, JSON/CSV export, exact-byte download, HTTP/email waits, test events, link/code extraction, callback checking, delayed responses, provider subscriptions, deletion, and activity history. See the generated tool reference.

Durable activity history

Every accepted HTTP, email, and DNS receipt and successful local mutation writes an activity record in the same transaction as its state change. Duplicate source deliveries also receive records. History includes notes, response settings, delayed responses, token rotation, subscriptions, deletion, and expiry. Read it with get_webhook_activity or POST /api/call with action: activity, the private token, a since cursor, and a bounded limit.

Minimal activity metadata remains after payload deletion and expiry. It excludes private tokens, provider credentials, bodies, notes, and signing secrets. Existing events are marked as imported; their previous mutation history cannot be reconstructed. The application appends records; this is not a cryptographic tamper-proof log. Rejected captures are not stored as accepted events.

Set verification_secret through configure_webhook to require SHA256 HMAC on raw HTTP bodies. Openhook accepts X-Openhook-Signature: sha256=… and GitHub's X-Hub-Signature-256. Invalid signatures are rejected before capture. Idempotency-Key and X-GitHub-Delivery deduplicate retries within an inbox.

Incoming URLs with ?openhook_wait=1 wait up to 20 seconds for an agent response. Start respond_to_next_request before sending such a request.

Configuration

SMTP rejects mail for unknown inboxes and never relays mail. DNS answers only for the configured zone and does not provide recursion.

Deploy

Use Dockerfile for the core service. Hosted deployments build its hosted target; compose.dokploy.yaml selects that image in a separate Dokploy project. Attach the Openhook domain to service openhook, port 8788. Its named data volume survives releases. See deployment notes.

Provider registration and local delivery

Call register_github_webhook, register_stripe_webhook, or register_linear_webhook to create a native inbox and subscribe at the source. Provider API credentials are used transiently and never saved. Raw signatures are checked before capture; Stripe and Linear timestamps are checked for replay. Call unregister_webhook before the inbox expires to remove the source subscription.

For local delivery, set OPENHOOK_TOKEN to your private inbox token, then run:

uv run openhook-listen --forward http://127.0.0.1:8080/webhook
# Or wake an already configured local OpenClaw:
uv run openhook-listen --openclaw

OpenClaw delivery also requires OPENCLAW_HOOKS_TOKEN. With no destination, the listener prints events as JSON. It connects outward over HTTPS, saves a cursor after successful delivery, and retries failed deliveries. Delivery is at least once: recipients should deduplicate by event ID. Each destination has its own cursor; run one listener per destination and token. Managed SSH tunnel provisioning is not included.

Verify

The website uses a centered text interface and the self-hosted Paper Mono v1.000 variable font and the approved Openhook logo. Public pages and live tool schemas are rendered in HTML before JavaScript runs. Agent entry points include /agents.md, /skill.md, /llms.txt, /llms-full.txt, /docs.md, and /openapi.json. Its webhook demo creates an inbox, sends a real callback, and reads the captured event. Refresh asset versions after editing web/:

bun run build

uv run --all-packages --extra dev pytest
node --check web/assets/app.js

Tests exercise native HTTP capture, private-token isolation, signature checks, idempotency, persistence, expiry, MCP, and real local SMTP and UDP/TCP DNS.

MIT licensed. Required third-party notices are in THIRD_PARTY_NOTICES.md.

Hosted development and contributing

The core package does not include billing adapters or read operator payment/login credentials. The separately installed hosted/ package adds GitHub identity, revocable agent keys, owned inboxes, and verified paid-invoice entitlements. See hosted operations for configuration, limits, test-mode requirements, and launch dependencies. No real merchant or paid launch is implied by the presence of this code.

See contributing and security reporting.