Connect with one prompt

Paste one prompt into Claude Code, Codex, Cursor or any agent that can run commands in a terminal. The agent tests one of your webhooks with a temporary endpoint, then connects itself to your Hooklistener account. You approve one link and read the agent a code. Your client does not need OAuth support, and you do not need an API key.

The prompt

Copy it from AI agents in the app (https://app.hooklistener.com/agents) or from the Hooklistener home page:

Use Hooklistener (https://app.hooklistener.com) to prove this project's webhook handling works, then keep it set up for next time.

1. Prove it, no account needed: follow https://app.hooklistener.com/llms.txt to create a temporary endpoint. Find where this app receives webhooks, have me send one real test event to the endpoint, and confirm it arrived. Then send the captured request to the local handler with curl and tell me what it answered. If the app receives no webhooks, skip to step 2.
2. Keep it: follow https://app.hooklistener.com/agent.md. Ask for access with the endpoint's id and claim token, send me the approval link, then trade the code I read back to you for a Hooklistener token. Never print it or commit it. Approving keeps the endpoint and what it captured.
3. Connect: add the Hooklistener MCP server with that token as agent.md shows, then add a short Hooklistener section to AGENTS.md (or CLAUDE.md) saying how to test webhooks here next time.

If the app also sends signup or login emails, tell me: testing those needs the account from step 2. If anything is missing, ask me before continuing.

The anonymous debugger on the home page has its own Copy prompt for your agent button. That prompt hands the agent the endpoint you already have open, so it can read what arrived and keep it.

What happens

1. A test with no account. The agent creates a temporary endpoint (it lasts 24 hours) and asks you to send one test event to it from Stripe, GitHub or whatever calls your app. It reads what arrived, sends the same request to your local handler, and tells you what the handler answered.
2. One approval. The agent gives you a link like https://app.hooklistener.com/agent?token=…. Sign in or create a free account, pick an organization and an access level, and approve. If the agent tested with a temporary endpoint, approving keeps it under the name you choose, with everything it captured. The page then shows a code like KQPT-WMRD. Read it to your agent.
3. Connected. The agent trades the code for a token, adds the Hooklistener MCP server to its own configuration, and writes a short Hooklistener section in your project's AGENTS.md or CLAUDE.md so later sessions know how to test your webhooks. Restart the agent to load the Hooklistener tools.

The approval page updates when the agent connects, and the connection appears under AI agents labelled Agent prompt.

Access levels

Access	What the agent can do
Full access (default)	Create and delete endpoints and inboxes, read what they capture, and replay requests to URLs it chooses.
Read only	Read endpoints, captured requests and emails. It cannot create anything, so it cannot set up new endpoints for you.

Security

• The code ties the token to your agent. The agent holds a secret of its own, and the code is useless without it. If someone sends you an approval link they started, approving it gives them nothing unless you also hand them the code. Only approve requests you just started from your own agent.
• Short windows. A request expires after 15 minutes. After you approve, the code works for 10 minutes and allows 5 wrong tries. If you lose the code, open the link again and get a new one; the old code stops working.
• The token is for the MCP server only. It is never shown to you. The agent keeps it in ~/.hooklistener/agent.json and in its own MCP configuration, outside your repository. It lasts 90 days from its last use.
• Disconnect at any time. Open AI agents and click Disconnect next to the connection. Removing someone from the organization also ends their agents' access.

Testing a local handler

Hooklistener's servers cannot reach localhost on your machine. To test a handler running locally, the agent reads the captured request from Hooklistener and sends it to your handler itself.

If your handler verifies signatures, it needs the signing secret of the provider endpoint that points at Hooklistener. That is usually a test endpoint with its own secret, not the one your production configuration uses.

For agents and integrators

The steps agents follow are at https://app.hooklistener.com/agent.md. They use two public endpoints:

Endpoint	Body	Returns
POST /api/v1/agent/connect	agent, project, optional scope (full_access or read_only), and optionally endpoint_id, claim_token and endpoint_name to keep an anonymous endpoint	connect_token, approval_url, expires_at
POST /api/v1/agent/connect/complete	connect_token, code	access_token, mcp_url, organization, scope, expires_at, and endpoint when one was kept

Errors carry an error message and an error_code: pending, wrong_code (with attempts_left), expired, too_many_attempts, denied, completed, not_found, not_a_member, invalid_scope, invalid_claim and rate_limited. The token goes in the MCP client's configuration as an Authorization: Bearer header.