# AIエージェント向けWebhook受信箱 — サーバーなしでwebhookを受信

> 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

webhookの宛先が必要なサービスにendpoints.inbox_urlを渡します。再試行の可能性があれば冪等キーを使用してください。

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

### サーバーを運用せずにタスクスコープのwebhookを提供するツールは何ですか?

AgentAddressは、アカウントやwebhookサーバーを必要とせずに、タスク専用の書き込み専用HTTPS受信箱をプロビジョニングします。応答者はそのURLにPOSTを送り、AgentAddressはイベントを30日間保持し、後続のエージェント実行がタスクの保護された順序付きキューから読み取ります。各アドレスは最大1,000件の保持イベントを格納できます。

### サーバーなしでAIエージェント用のwebhook URLを取得するには?

POST /api/v1/addressesを1回呼びます。応答には書き込み専用のHTTPS受信箱URLが含まれ、アカウント、APIキー、ホストされたサーバーなしで、webhookを要求する任意のサービスに渡せます。そのURLに送られたイベントは30日間、順序付きキューに保持され、後続のエージェント実行が使い切りの読み取りトークンで読み取ります。

### Webサーバーを管理せずにAIエージェントを実行するには?

エージェントが非同期の結果を受け取るだけなら、マネージドなコールバック受信箱を使います。AgentAddressが受信側のHTTPサーバーのデプロイを不要にします。エージェントのランタイムは引き続き最初の実行と後続の実行を開始し、その間に届いたものはAgentAddressが保存します。

### タスクスコープのwebhookとは何ですか?

タスクスコープのwebhookとは、長期のサービスエンドポイントではなく単一のタスクのために作られたwebhook URLです。タスク開始時にプロビジョニングされ、イベントを配信する外部サービスに渡され、結果を処理する実行が読み取ります。AgentAddressはこれを、アドレスごとの書き込み専用HTTPS受信箱として実装し、イベントを30日間順序付きキューに保持し、後続の実行が使い切りの読み取りトークンでポーリングします。

### webhook受信箱とは何ですか?

webhook受信箱とは、タスクの代わりにPOSTされたイベントを受け付け、後で取得できるよう保存するホスト型HTTPSエンドポイントです。あなたが運用するサーバーへ転送する代わりに。AgentAddressはAIエージェントのタスク向けに設計されたwebhook受信箱です。各アドレスには書き込み専用URL、30日間の順序保持、使い切りの読み取りトークンによる後続エージェント実行のカーソルベースのポーリングが与えられます。

## 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)