Openhook

Openhook

An event inbox for AI agents. Create a public URL, wait for a callback, inspectwhat 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, orconnect your agent. Optional hosted Pro providespersistent inboxes and account recovery; see the currentavailability and plans. Self-hosting remains MITlicensed with no Openhook account or subscription.

Practical recipes: local forwarding,GitHub push callbacks, andStripe 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 theoriginal bytes, then deletes its inbox and payload. The private token stays inmemory. 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. Installingthe 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 hostedhttps://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 deletingthat inbox requires the token as a tool argument. Persistent hosted inboxesrequire a separate Openhook account key.

Ask the agent to create a disposable inbox, then give its public URL to thesystem 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 askOpenCode to create a disposable inbox and inspect a synthetic callback. NoOpenhook account is needed for a disposable inbox. Keep its private token outof 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 notprove that your application's handler processed the event.

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

Run it

From the checkout, install uvand 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 MCPendpoint share one service and one durable store.

Connect an MCP client to http://127.0.0.1:8788/mcp, or useuv run openhook for stdio. A local stdio process shares the same databasewith a running HTTP process when both use the same OPENHOOK_DATABASE.The HTTP process must be running to receive HTTP callbacks. Check the same loopagainst 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 onlyproves your local server works.

GitHub releases provideversioned source and Python distributions when available. The openhook-mcppackage is not currently published on PyPI; use the source checkout or a releaseartifact 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 compromisedmanagement 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 onlywhen 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 writesan activity record in the same transaction as its state change. Duplicate sourcedeliveries 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 excludesprivate tokens, provider credentials, bodies, notes, and signing secrets.Existing events are marked as imported; their previous mutation history cannotbe reconstructed. The application appends records; this is not a cryptographictamper-proof log. Rejected captures are not stored as accepted events.

Set verification_secret through configure_webhook to require SHA256 HMACon raw HTTP bodies. Openhook accepts X-Openhook-Signature: sha256=… andGitHub'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 onlyfor the configured zone and does not provide recursion.

Deploy

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

Provider registration and local delivery

Call register_github_webhook, register_stripe_webhook, orregister_linear_webhook to create a native inbox and subscribe at the source.Provider API credentials are used transiently and never saved. Raw signaturesare 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 acursor after successful delivery, and retries failed deliveries. Delivery isat least once: recipients should deduplicate by event ID. Each destination hasits own cursor; run one listener per destination and token. Managed SSH tunnelprovisioning is not included.

Verify

The website uses a centered text interface and the self-hosted Paper Monov1.000 variable font and the approved Openhook logo. Public pages and live toolschemas 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/logincredentials. The separately installed hosted/ package addsGitHub identity, revocable agent keys, owned inboxes, and verified paid-invoiceentitlements. See hosted operations for configuration,limits, test-mode requirements, and launch dependencies. No real merchant or paidlaunch is implied by the presence of this code.

See contributing and security reporting.