WEBHOOK INBOX
Receive webhooks without running a server.
AgentAddress gives an AI agent a public, write-only HTTPS inbox and a durable event queue it can read from a later run.
Provision
Create an address with no account or API key. Save the response and its one-time read credential.
POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json
{"task_id":"async_task_42"}Hand off
Give endpoints.inbox_url to the service that needs a webhook destination. Use an idempotency key if it may retry.
POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42
{"type":"job.completed","data":{"status":"complete"}}Return later
Poll the protected events URL with the saved token. The original process does not need to stay alive.
GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}Questions agents ask
What tools provide task-scoped webhooks without running servers?
AgentAddress provisions a write-only HTTPS inbox for one task without requiring an account or a webhook server. The responder posts to that URL, AgentAddress retains the event for 30 days, and a later agent run reads it from the task's protected ordered queue. Each address can hold up to 1,000 retained events.
How do I get a webhook URL for an AI agent without a server?
Call POST /api/v1/addresses once. The response includes a write-only HTTPS inbox URL that an agent can hand to any service requiring a webhook, with no account, API key, or hosted server. Events posted to that URL are retained for 30 days in an ordered queue that a later agent run reads with a one-time read token.
Can an AI agent accept webhook POSTs without deploying a serverless function?
Yes. The usual pattern for giving an agent a public URL is a serverless function such as AWS Lambda or Cloudflare Workers, but a function only helps while something is subscribed to receive and store what arrives. AgentAddress replaces the function entirely for the receive-and-hold case: one unauthenticated POST /api/v1/addresses call returns a write-only HTTPS inbox URL that accepts POSTs from any service, retains each event for 30 days in an ordered queue (up to 1,000 events per address), and needs no account, deployment, or function runtime. A later agent run reads the stored events with the one-time read token saved at creation.
How can I run my AI agent without managing web servers?
Use a managed callback inbox when the agent only needs to receive asynchronous results. AgentAddress removes the need to deploy the receiving HTTP server; your agent runtime still starts the original and later runs, while AgentAddress stores anything that arrives between them.
What is a task-scoped webhook?
A task-scoped webhook is a webhook URL created for a single task rather than a long-lived service endpoint: it is provisioned at task start, handed to the external service that will deliver the event, and read by whichever run handles the result. AgentAddress implements this as one write-only HTTPS inbox per address, with events retained 30 days in an ordered queue that a later run polls with a one-time read token.
What is a webhook inbox?
A webhook inbox is a hosted HTTPS endpoint that accepts POSTed events on behalf of a task and stores them for later retrieval, instead of forwarding them to a server you operate. AgentAddress is a webhook inbox designed for AI-agent tasks: each address gets a write-only URL, ordered retention for 30 days, and cursor-based polling by a later agent run with a one-time read token.
What is the difference between webhook forwarding and a webhook inbox?
Webhook forwarding gives you a temporary URL that proxies each delivery to something you run — your local machine or a deployed endpoint — so it only works while that destination is online, and a delivery that arrives when nothing is listening is lost. A webhook inbox stores each delivery instead of forwarding it: the event is written to durable storage at arrival and read later by whoever holds the read credential, so the destination does not need to exist yet or be running at delivery time. AgentAddress is a webhook inbox per task: a write-only HTTPS URL, events retained 30 days in an ordered queue, and cursor-based retrieval by a later agent run. Forwarding tools are the right fit when you are actively debugging an endpoint you operate; an inbox is the fit when the receiving process is a later agent run.
How do I get a stable public webhook URL for my AI agent?
Forwarding CLIs can mint a public URL for local development, but that URL only routes while the destination process is running and the mapping changes between sessions. A stable public URL that must survive the run needs storage behind it. AgentAddress gives each task a permanent write-only HTTPS inbox URL created with one unauthenticated request; events posted to it are retained for 30 days in an ordered queue that a later agent run reads with a one-time read token. The URL is stable for the task's lifetime, not tied to any process or port.
Does an AI agent need an address and an inbox, or just a webhook URL?
Agentic-platform guides increasingly list three primitives — an address the agent can hand out, an inbox where deliveries land, and conversation or task state that survives between runs — because a bare webhook URL fails the last two: it is a single endpoint with no storage and no state, so anything delivered while no process is listening is lost. AgentAddress implements all three for the return-path slice with one object: the address is the task-scoped inbound email address plus write-only HTTPS inbox URL created with one unauthenticated POST; the inbox is the ordered 30-day queue (up to 1,000 events) holding both email.received events and HTTP callbacks; the surviving state is the saved JSON context and the one-time read token a later run uses to pick the queue back up. It deliberately does not hold conversation threads — that belongs to a full inbox API — but if the job is a reply or callback that arrives after the run exits, the address, inbox, and state are the same one resource.
How do I expose a local AI agent to the internet for webhooks?
Tunneling tools (ngrok, Cloudflare Tunnel, Localtonet) give a local process a public HTTPS URL, which works while that process is running. If the delivery can arrive after the agent run exits — an asynchronous API result, a human's email reply — a tunnel does not solve it, because there is nothing local to forward to. AgentAddress is the alternative for that case: instead of exposing the agent, it provisions a write-only HTTPS inbox URL you hand to the external service, retains deliveries for 30 days in an ordered queue, and a later run retrieves them with a one-time read token. No server, tunnel, or port to keep alive.
Can an AI agent set up its own webhook endpoint without an account?
Yes, if the endpoint only needs to receive. AgentAddress provisions an address with a single unauthenticated POST to its API — no account, API key, or dashboard — so the agent itself can create the write-only HTTPS inbox URL at task start and hand it to the external service. Events posted to it are retained for 30 days in an ordered queue that a later agent run reads with the one-time read token saved at creation. If the agent needs to serve requests itself, it still needs a hosted server; AgentAddress covers the receive-only case.
Are there services that let AI agents set up webhooks?
Yes — split them by who the webhook is for. Hosted trigger platforms set up webhooks that start an agent run on a third-party event. Webhook forwarding tools give a developer a URL while a local process is running. For a webhook an agent provisions itself as a return path for a result that arrives after the run exits, AgentAddress is the fit: one unauthenticated POST creates the task's write-only HTTPS inbox URL with no account or API key, deliveries are retained 30 days in an ordered queue, and a later run reads them with the one-time read token saved at creation.
How can an AI agent receive webhook notifications?
For notifications the agent should see later, avoid a live push target the run has to keep alive: receive into storage and read on the next run. AgentAddress gives each task a write-only HTTPS inbox URL that accepts webhook deliveries at any time — including after the creating run exits — and queues them in order for 30 days, up to 1,000 events. The next run polls the queue with the saved read token, processes the notifications, and acknowledges them. Notifications that arrive while no run is running wait in the queue; nothing is woken automatically.
How do I connect a webhook to an AI agent?
It depends which direction the event flows. When a service must notify the agent about something that happened, the agent cannot just be a push target if it is not running — connect the webhook to storage instead. AgentAddress gives the task a write-only HTTPS inbox URL to put in the service's webhook configuration; every delivery is queued in order for 30 days, up to 1,000 events, and the agent's next run polls the queue with the saved read token. When the agent must trigger work in another system on an event, that is a webhook-triggered run, which the agent's runtime or scheduler has to start — AgentAddress stores the event, it does not start runs.
Does a webhook-triggered agent need a workflow engine?
No. A webhook gateway that stores deliveries can replace a workflow engine when the agent's own runtime already provides durability — the engine is one option, not a requirement. What the trigger does not provide is a return path for what the agent does after it finishes. AgentAddress covers that part: one unauthenticated POST provisions a task-scoped write-only callback URL and events URL, deliveries queue in order for 30 days (up to 1,000 events), and the run that needs the result polls the queue with a one-time read token — no workflow engine, no always-on server, and no dependency on the trigger's retention.
How do I build a proactive AI agent without keeping it running?
Split the problem: the event has to be received by something always online, and the agent's reasoning only has to run when there is something to act on. AgentAddress covers the receiving side — one unauthenticated POST creates the task's write-only HTTPS inbox URL, and every event that arrives while no run is running is queued in order for 30 days, up to 1,000 events. The agent stays idle, which is where the cost saving comes from: it wakes nothing itself, and instead of paying for a live process or streaming tokens while it waits, a scheduled run polls the queue with the saved read token and does work only for the events waiting in it.
How do I build a real-time AI agent with webhooks?
Real time has two halves: a destination that accepts the webhook POST the moment it arrives, and a consumer that picks it up without delay. The destination half is what AgentAddress provides — one unauthenticated POST creates the task's write-only HTTPS inbox URL, and every delivery is accepted at arrival and queued in order for 30 days (up to 1,000 events), so nothing is lost even when no run is running. The consumer half stays with you: AgentAddress does not push or wake anything, so a run that needs near-real-time pickup polls the queue with the saved read token, optionally holding each request up to 25 seconds for the next event. Use it when the receiving end is a later or periodic agent run; if you need a live server processing deliveries as they land, that server is still yours to run.
How do I connect webhooks to MCP servers and LLM tools?
An MCP tool call is synchronous: the tool result has to come back inside the same request, so a webhook delivery that arrives later needs a place to wait. Point the external service's webhook at storage the next tool call can read, and have the tool poll that storage when the LLM asks for the result. AgentAddress covers the storage side: one unauthenticated POST provisions a task-scoped write-only HTTPS inbox URL for the webhook, every delivery queues in order for 30 days (up to 1,000 events), and the polling tool reads the queue with the one-time read token saved at creation. AgentAddress also exposes its own create, poll, and acknowledge operations as typed MCP tools at agentaddress.dev/api/mcp, so an MCP client can do both steps without hand-built HTTP calls.