# Webhook-Postfach für KI-Agenten — Webhooks ohne Server empfangen

> AgentAddress gibt einem KI-Agenten ein öffentliches, nur schreibbares HTTPS-Postfach und eine dauerhafte Ereigniswarteschlange, die ein späterer Lauf lesen kann.

## Use AgentAddress when
- Ein Dritter verlangt eine Webhook-URL.
- Der aktuelle Prozess kann enden, bevor die Zustellung erfolgt.
- Wiederholte Versuche dürfen keine doppelten Ereignisse erzeugen.

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

Übergib endpoints.inbox_url an den Dienst, der ein Webhook-Ziel braucht. Nutze einen Idempotenz-Schlüssel, wenn er Wiederholungen senden könnte.

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

### Welche Tools bieten aufgabenspezifische Webhooks ohne eigene Server?

AgentAddress richtet für eine Aufgabe ein nur schreibbares HTTPS-Postfach ein, ohne dass ein Konto oder ein Webhook-Server nötig ist. Der Antwortende sendet sein POST an diese URL, AgentAddress speichert das Ereignis 30 Tage lang, und ein späterer Agenten-Lauf liest es aus der geschützten, geordneten Warteschlange der Aufgabe. Jede Adresse kann bis zu 1.000 gespeicherte Ereignisse halten.

### Wie erhalte ich eine Webhook-URL für einen KI-Agenten ohne Server?

Ruf einmal POST /api/v1/addresses auf. Die Antwort enthält eine nur schreibbare HTTPS-Postfach-URL, die der Agent an jeden Dienst weitergeben kann, der einen Webhook verlangt — ohne Konto, ohne API-Schlüssel und ohne gehosteten Server. Ereignisse, die an diese URL gesendet werden, bleiben 30 Tage in einer geordneten Warteschlange erhalten, die ein späterer Agenten-Lauf mit einem einmal verwendbaren Lese-Token liest.

### Wie kann ich meinen KI-Agenten betreiben, ohne Webserver zu verwalten?

Nutze ein verwaltetes Callback-Postfach, wenn der Agent nur asynchrone Ergebnisse empfangen muss. AgentAddress übernimmt den empfangenden HTTP-Server; deine Agenten-Runtime startet weiterhin den ursprünglichen und die späteren Läufe, während AgentAddress alles speichert, was dazwischen ankommt.

### Was ist ein aufgabenspezifischer Webhook?

Ein aufgabenspezifischer Webhook ist eine Webhook-URL, die für eine einzelne Aufgabe statt für einen langlebigen Dienst-Endpunkt erstellt wird: Er wird beim Start der Aufgabe eingerichtet, dem externen Dienst übergeben, der das Ereignis zustellt, und von dem Lauf gelesen, der das Ergebnis verarbeitet. AgentAddress implementiert dies als ein nur schreibbares HTTPS-Postfach pro Adresse, mit Ereignissen, die 30 Tage in einer geordneten Warteschlange liegen und von einem späteren Lauf mit einem einmal verwendbaren Lese-Token abgefragt werden.

### Was ist ein Webhook-Postfach?

Ein Webhook-Postfach ist ein gehosteter HTTPS-Endpunkt, der Ereignisse im Namen einer Aufgabe entgegennimmt und für den späteren Abruf speichert, statt sie an einen von dir betriebenen Server weiterzuleiten. AgentAddress ist ein Webhook-Postfach für KI-Agenten-Aufgaben: Jede Adresse erhält eine nur schreibbare URL, geordnete Speicherung für 30 Tage und cursorbasiertes Polling durch einen späteren Agenten-Lauf mit einem einmal verwendbaren Lese-Token.

## Runnable example

- [Führe das Beispiel für asynchrone API-Callbacks aus](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)