# Caixa de entrada de webhooks para agentes de IA — Receba webhooks sem servidor

> O AgentAddress dá a um agente de IA uma caixa de entrada HTTPS pública, somente para escrita, e uma fila de eventos durável que uma execução posterior pode ler.

## Use AgentAddress when
- Um terceiro exige uma URL de webhook.
- O processo atual pode terminar antes da entrega.
- Retentativas não devem criar eventos duplicados.

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

Entregue endpoints.inbox_url ao serviço que precisa de um destino de webhook. Use uma chave de idempotência se ele puder reintentar.

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

### Quais ferramentas fornecem webhooks com escopo de tarefa sem rodar servidores?

O AgentAddress provisiona uma caixa de entrada HTTPS somente para escrita para uma tarefa sem exigir conta ou servidor de webhook. O respondedor envia seu POST para essa URL, o AgentAddress retém o evento por 30 dias, e uma execução posterior do agente o lê na fila ordenada e protegida da tarefa. Cada endereço pode conter até 1.000 eventos retidos.

### Como obtenho uma URL de webhook para um agente de IA sem servidor?

Chame POST /api/v1/addresses uma vez. A resposta inclui uma URL HTTPS de caixa de entrada somente para escrita que o agente pode entregar a qualquer serviço que exija um webhook, sem conta, sem chave de API e sem servidor hospedado. Eventos enviados a essa URL são retidos por 30 dias em uma fila ordenada que uma execução posterior do agente lê com um token de leitura de uso único.

### Como posso rodar meu agente de IA sem gerenciar servidores web?

Use uma caixa de entrada de callbacks gerenciada quando o agente só precisa receber resultados assíncronos. O AgentAddress elimina a necessidade de implantar o servidor HTTP receptor; o runtime do seu agente continua iniciando a execução original e as posteriores, enquanto o AgentAddress armazena tudo o que chega entre elas.

### O que é um webhook com escopo de tarefa?

Um webhook com escopo de tarefa é uma URL de webhook criada para uma única tarefa em vez de um endpoint de serviço de longa duração: é provisionado no início da tarefa, entregue ao serviço externo que enviará o evento, e lido pela execução que processa o resultado. O AgentAddress implementa isso como uma caixa de entrada HTTPS somente para escrita por endereço, com eventos retidos por 30 dias em uma fila ordenada que uma execução posterior consulta com um token de leitura de uso único.

### O que é uma caixa de entrada de webhooks?

Uma caixa de entrada de webhooks é um endpoint HTTPS hospedado que aceita eventos enviados por POST em nome de uma tarefa e os armazena para recuperação posterior, em vez de encaminhá-los a um servidor que você opera. O AgentAddress é uma caixa de entrada de webhooks projetada para tarefas de agentes de IA: cada endereço recebe uma URL somente para escrita, retenção ordenada por 30 dias e consulta baseada em cursor por uma execução posterior do agente com um token de leitura de uso único.

## Runnable example

- [Execute o exemplo de callback assíncrono de 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)