openhook
When this workflow fits
Use this for asynchronous notifications such as repository events or completed jobs, where you need to inspect and process a payload. It also lets an agent read the stored event independently of your local handler.
Openhook acknowledges the sender before local forwarding. The sender cannot see your local response, status code or response timing. If you need synchronous verification challenges, interactive callbacks or end-to-end response testing, use public routing directly to your handler instead.
1. Create the public inbox
Follow the webhook testing quickstart or call create_webhook over MCP. Save the private management token. Give the capture URL to the provider; do not give it your localhost address.
2. Install the listener from source
Install Python 3.10 or later and uv, then run:
git clone https://github.com/openhook-dev/openhook-inbox.git cd openhook-inbox uv sync
The repository includes openhook-listen. These instructions use the current source distribution and do not require a global Openhook API key.
3. Forward to your local handler
Start your app on port 8080 with a /webhook route. Set OPENHOOK_TOKEN through your local secret manager or environment, then run from the checkout:
uv run openhook-listen --url https://openhook.dev \ --forward http://127.0.0.1:8080/webhook
The listener forwards the original request bytes and applicable headers. It removes hop-by-hop headers and lets the HTTP client set the local host and content length. It sends to the exact destination above; it does not recreate arbitrary captured URL paths or query strings.
Retries, cursors and signatures
The listener saves its cursor after a successful local HTTP response. A connection failure or unsuccessful response leaves the cursor available for retry. This is at-least-once delivery: make side effects idempotent and use the provider event ID, or Openhook event UUID, to recognize duplicate delivery.
Cursor files live under ~/.openhook/inbox-listeners by default. Keep one listener per inbox and destination. Changing the destination creates a separate cursor and may replay retained events.
Match the signing secret used by your local verifier to the sender’s secret. Stored bytes preserve the payload, but timestamp-based signature checks can reject an old replay. For example, a delayed Stripe event can fall outside your verifier’s timestamp tolerance. Use fresh sandbox events to test that path; do not disable signature validation in production.
What happens while the laptop is asleep?
Events remain available within the inbox’s retention and capacity limits. Restarting the listener resumes from its saved cursor. If payloads expired or capture failed at capacity, the listener cannot recover them. Consult retention limits and your provider’s delivery history.
A listener must be running to forward events. Openhook does not automatically launch a closed editor or agent session. For a configured OpenClaw hook, see the notification guide.
Inspect first, then clean up
Use get_requests and get_request through MCP to inspect a failed event. Keep secrets and customer data out of shared logs. Stop the listener, unregister provider subscriptions and delete the inbox after a disposable test.
Next: verify a GitHub webhook or operate the receiver yourself.