# 面向 AI 代理的 Webhook 收件箱 — 无需服务器即可接收 webhooks

> AgentAddress 为 AI 代理提供公开的只写 HTTPS 收件箱，以及可供后续运行读取的持久事件队列。

## Use AgentAddress when
- 第三方要求提供 webhook URL。
- 当前进程可能在投递之前退出。
- 重试不得产生重复事件。

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42"}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

将 endpoints.inbox_url 交给需要 webhook 目标的service。如果对方可能重试，请使用幂等键。

POST {endpoints.inbox_url}
Content-Type: application/json
Idempotency-Key: result-42

{"type":"job.completed","data":{"status":"complete"}}

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Common questions

### 哪些工具可以在不运行服务器的情况下提供任务级 webhooks?

AgentAddress 为单个任务提供只写 HTTPS 收件箱，无需账号或 webhook 服务器。响应方 POST 到该 URL，AgentAddress 将事件保留 30 天，之后由代理的后续运行从任务的受保护有序队列中读取。每个地址最多可容纳 1,000 个保留事件。

### 如何在没有服务器的情况下为 AI 代理获取 webhook URL?

调用一次 POST /api/v1/addresses。响应包含只写的 HTTPS 收件箱 URL，代理可以将其交给任何要求 webhook 的服务——无需账号、API 密钥或托管服务器。发送到该 URL 的事件会在有序队列中保留 30 天，由代理后续运行用一次性读取令牌读取。

### 如何在不必管理 web 服务器的情况下运行我的 AI 代理?

当代理只需接收异步结果时，可使用托管回调收件箱。AgentAddress 免去了部署接收端 HTTP 服务器的需要；代理运行时依然会启动最初及后续的运行，而 AgentAddress 则保存两次运行之间到达的所有内容。

### 什么是任务级 webhook?

任务级 webhook 是为单个任务而非长期服务端点创建的 webhook URL：在任务开始时开通，交给将投递事件的外部服务，由处理结果的运行读取。AgentAddress 将其实现为每个地址一个只写 HTTPS 收件箱，事件在有序队列中保留 30 天，后续运行使用一次性读取令牌进行轮询。

### 什么是 webhook 收件箱?

webhook 收件箱是托管的 HTTPS 端点，代替任务接受 POST 的事件并存储以便后续取回，而不是转发到你运营的服务器。AgentAddress 是专为 AI 代理任务设计的 webhook 收件箱：每个地址获得一个只写 URL、30 天的有序保留，以及后续代理运行以一次性读取令牌进行的基于 cursor 的轮询。

## Runnable example

- [运行异步 API 回调示例](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/async-api)
- [Controlled cross-run verification and its limits](https://github.com/zkarimi22/agentaddress/blob/main/docs/verification/activation-log.md)

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)