AI Agents: Sandbox and Registration

An AI agent can use webhooks.cc before anyone signs up. It registers itself through auth.md, the agent registration protocol webhooks.cc implements (version 0.6), and gets a sandbox: a few temporary endpoints that capture webhooks for a day and that only the agent can read.

The full protocol, with request and response examples, is at webhooks.cc/auth.md. Agents read that document directly; this page explains the same flow for people.

What an agent gets without an account

• Up to 3 endpoints at a time, each with a capture URL like https://go.webhooks.cc/w/<slug>.
• 25 captured requests per endpoint and 100 per registration in all.
• The registration and its endpoints expire 24 hours after the agent registered, and are deleted, with everything they captured, within minutes after that.
• Captures are readable only with the agent's own access token. Nobody else can list or read them, and they never appear in anyone's dashboard.

Sandbox endpoints only capture. They answer every webhook with a plain 200 and have no mock responses, notification webhooks, signature verification, email address, or forwarding. When an endpoint or the registration has used its requests, the capture URL answers 429.

How registration works

1. Discover. The agent finds the registration endpoints in /.well-known/oauth-authorization-server, or follows the WWW-Authenticate header of any 401 from the API.
2. Prove some work. Anonymous registration needs a solved proof-of-work challenge from POST /api/agent/identity/challenge: many SHA-256 hashes, a few seconds of CPU. It keeps scripts from filling the sandbox for free. A registration request without one gets a challenge back, so an agent needs no extra knowledge.
3. Register. POST /api/agent/identity with { "type": "anonymous", "proof_of_work": ... } returns a signed identity assertion and a claim token.
4. Get an access token. The agent exchanges the assertion at POST /api/oauth2/token for an access token that lasts one hour. It can exchange again for a new one until the registration expires.
5. Use the sandbox. With that token the agent creates endpoints at /api/agent/sandbox/endpoints and reads what they captured.

Each IP address can register 5 times an hour. An agent that cannot run code, and so cannot solve the challenge, can register with your email instead ("type": "service_auth"): it gets no sandbox, and nothing works until you connect it as described below.

Connecting an agent to your account

When you want to keep what an agent set up, or let it work in your account, connect it:

1. The agent names your email and gets a link and a 6-digit code. It shows you both, for example: "Open this link, sign in, and enter 123456".
2. Open the link and sign in, or sign up, with that email address. A link for someone else's address does not work in your account.
3. Check the page: it shows the name the agent gave itself, when it registered, and which sandbox endpoints will move into your account. Enter the code, or decline.

After you connect it:

• Its sandbox endpoints become ordinary endpoints in your account, with the same URLs and the requests they already captured. They no longer expire, and new captures count against your plan.
• The agent can use the API on your behalf, like an API key: manage endpoints and read what they capture. It cannot change your API keys, billing or account settings.
• You get an email saying an agent was connected.

The code works for 15 minutes and for 5 tries; the agent can ask for a new one. An account can connect up to 10 agents.

Revocation and expiry

• Disconnect a connected agent under Account, Connected agents. Its access stops at once; endpoints it brought stay in your account.
• An agent can drop one of its access tokens at POST /api/oauth2/revoke.
• An unclaimed registration stops working 24 hours after registration; its tokens, endpoints and captured requests are deleted within minutes after that. There is nothing to clean up.
• Agents that used the earlier version of the protocol (auth.md 0.1) get 410 endpoint_moved from the old registration endpoint and a pointer to /auth.md. Its email-code flow keeps working for older SDK and MCP versions until November 30, 2026.