> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://agentinbox.space/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://agentinbox.space/_mcp/server. # Обзор вебхуков > Узнайте, как использовать вебхуки для отзывчивых, событийно-ориентированных почтовых агентов с Agent Inbox. Вебхуки — самый удобный способ получать информацию о том, что происходит с вашей почтой, в реальном времени. Вместо постоянных запросов к API Agent Inbox, есть ли новое письмо (так называемый polling), вы регистрируете URL, и мы отправляем вам `POST` с подробностями сразу после события. Такой событийный подход эффективнее и позволяет строить быстрых, отзывчивых агентов, которые мгновенно реагируют на входящие сообщения. ## Зачем нужны вебхуки? * **Скорость в реальном времени:** диалоговые агенты могут отвечать на входящие письма за секунды. * **Эффективность:** не нужен постоянный polling — экономятся ресурсы и упрощается логика приложения. ## Доступные события Agent Inbox поддерживает семь типов событий вебхуков. При создании вебхука можно подписаться на отдельные типы или на все сразу. Полное описание полезной нагрузки — в разделе [События вебхуков](/events). **События сообщений:** * **`message.received`** — новое письмо получено и обработано в одном из ваших ящиков * **`message.sent`** — сообщение успешно отправлено из вашего ящика * **`message.delivered`** — доставка подтверждена почтовым сервером получателя * **`message.bounced`** — доставка не удалась, письмо отскочило * **`message.complained`** — получатель пометил ваше письмо как спам * **`message.rejected`** — отправка отклонена до отправки (валидация или политика) **События домена:** * **`domain.verified`** — пользовательский домен успешно верифицирован ## Как устроен поток вебхука Процесс простой: #### 1. Создайте endpoint вебхука Это публичный URL на вашем сервере, принимающий `POST`. Для локальной разработки удобен инструмент вроде `ngrok`: безопасный публичный URL, туннелирующий на вашу машину. Endpoint должен сразу отвечать `200 OK`, чтобы подтвердить приём, а обработку полезной нагрузки выполнять в фоне, чтобы не упереться в таймауты. #### 2. Зарегистрируйте endpoint в Agent Inbox URL регистрируется через API Agent Inbox. При создании вебхука вы указываете URL endpoint и типы событий, которые хотите получать. ```python client.webhooks.create( url="https://.ngrok-free.app/webhooks", event_types=["message.received", "message.sent"], ) ``` ```typescript await client.webhooks.create({ url: "https://.ngrok-free.app/webhooks", eventTypes: ["message.received", "message.sent"], }); ``` **`CLI`** ```bash title="CLI" # register a webhook endpoint agentinbox webhooks create \ --url https://.ngrok-free.app/webhooks \ --event-type message.received \ --event-type message.sent ``` Укажите нужные события; опустите `event_types`, чтобы подписаться на все типы. #### 3. Agent Inbox отправляет события Когда происходит событие (например, пришло новое письмо, доставка подтверждена или домен верифицирован), Agent Inbox отправляет `POST` с JSON на зарегистрированный URL. ## Структура полезной нагрузки В вебхуке есть `event_type` и `event_id`, плюс данные, зависящие от типа события. Ниже пример для `message.received`; у других событий другие объекты верхнего уровня (`send`, `delivery`, `bounce` и т. д.). Форму полезной нагрузки для каждого события см. в [Событиях вебхуков](/events). ### Ограничение размера полезной нагрузки Размер полезной нагрузки вебхука ограничен **1 МБ**. Если сообщение больше, Agent Inbox убирает из полезной нагрузки поля `text` и `html`, чтобы уменьшить размер. Остальные метаданные сохраняются. Встроенные в HTML картинки (в том числе data URI в base64) учитываются в размере и часто приводят к достижению лимита. Пропущенное содержимое всегда можно получить через API. После вебхука загрузите полное сообщение, чтобы получить тело и вложения: ```python # fetch the full message after receiving a webhook message = client.inboxes.messages.get( inbox_id=payload["message"]["inbox_id"], message_id=payload["message"]["message_id"], ) text_body = message.text html_body = message.html ``` ```typescript // fetch the full message after receiving a webhook const message = await client.inboxes.messages.get( payload.message.inbox_id, payload.message.message_id, ); const textBody = message.text; const htmlBody = message.html; ``` **`CLI`** ```bash title="CLI" # fetch the full message after receiving a webhook agentinbox inboxes:messages retrieve \ --inbox-id \ --message-id ``` **`Webhook Payload`** ```json Webhook Payload { "event_type": "message.received", "event_id": "evt_123abc...", "message": { "from_": ["sender@example.com"], "organization_id": "org_abc123...", "inbox_id": "inbox_def456...", "thread_id": "thd_ghi789...", "message_id": "", "labels": ["received"], "timestamp": "2023-10-27T10:00:00Z", "reply_to": ["reply-to@example.com"], "to": ["recipient@example.com"], "cc": ["cc-recipient@example.com"], "bcc": ["bcc-recipient@example.com"], "subject": "Email Subject", "preview": "A short preview of the email text...", "text": "The full text body of the email.", "html": "...", "attachments": [ { "attachment_id": "att_pqr678...", "filename": "document.pdf", "content_type": "application/pdf", "size": 123456, "inline": false } ], "in_reply_to": "", "references": ["", ""], "sort_key": "some-sort-key", "updated_at": "2023-10-27T10:00:05Z", "created_at": "2023-10-27T10:00:00Z" } } ``` ### Описание полей * **`event_type`** (`string`): тип события (например `message.received`, `message.sent`, `message.delivered`). Структура полезной нагрузки зависит от типа — см. [События вебхуков](/events). * **`event_id`** (`string`): уникальный идентификатор этой доставки события. * **`message`** (`object`): словарь с полными данными полученного письма. * **`from_`** (`array`): адрес отправителя. Подчёркивание в конце — чтобы не конфликтовать с ключевым словом Python. * **`organization_id`** (`string`): идентификатор вашей организации. * **`inbox_id`** (`string`): идентификатор ящика, куда пришло письмо. * **`thread_id`** (`string`): идентификатор цепочки (треда). * **`message_id`** (`string`): уникальный идентификатор этого сообщения. * **`labels`** (`array`): метки сообщения (например `received`, `sent`). * **`subject`** (`string`): тема письма. * **`preview`** (`string`): короткий текстовый превью тела. * **`text`** (`string`): тело в виде plain text. Может отсутствовать при превышении лимита 1 МБ. Если поля нет — загрузите сообщение через API. * **`html`** (`string`): HTML-тело, если есть. Может отсутствовать при превышении лимита 1 МБ. Если поля нет — загрузите сообщение через API. * **`attachments`** (`array`): метаданные вложений (`attachment_id`, `filename`, `content_type`, `size`, `inline`). Содержимое вложений в вебхук не входит — скачивайте через API. * **`in_reply_to`** (`string`): `message_id` письма, на которое это ответ, если применимо. ## Копировать в Cursor / Claude Скопируйте один из блоков ниже в Cursor или Claude, чтобы за один раз передать полное описание API вебхуков. **`Python`** ```python title="Python" """ Agent Inbox Webhooks — copy into Cursor/Claude. Setup: pip install agentinbox python-dotenv. Set AGENTINBOX_API_KEY in .env. Return 200 immediately; process payload in background. API reference: - webhooks.create(url, event_types?, inbox_ids?, pod_ids?, client_id?) - webhooks.get(webhook_id), webhooks.list(limit?, page_token?) - webhooks.update(webhook_id, add_inbox_ids?, remove_inbox_ids?, add_pod_ids?, remove_pod_ids?) - webhooks.delete(webhook_id) Events: message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified Payload: event_type, event_id, plus message/send/delivery/bounce/complaint/reject/domain. Verify with Svix (webhook.secret). """ import os from dotenv import load_dotenv from agentinbox import Agentinbox load_dotenv() client = Agentinbox(api_key=os.getenv("AGENTINBOX_API_KEY")) wh = client.webhooks.create(url="https://your-server.com/webhooks", event_types=["message.received"], client_id="my-webhook-v1") all_wh = client.webhooks.list() secret = client.webhooks.get(wh.webhook_id).secret ``` **`TypeScript`** ```typescript title="TypeScript" /** * Agent Inbox Webhooks — copy into Cursor/Claude. * * Setup: npm install agentinbox dotenv. Set AGENTINBOX_API_KEY in .env. * Return 200 immediately; process payload in background. * * API reference: * - webhooks.create({ url, eventTypes?, inboxIds?, podIds?, clientId? }) * - webhooks.get(webhookId), webhooks.list({ limit?, pageToken? }) * - webhooks.update(webhookId, { addInboxIds?, removeInboxIds?, addPodIds?, removePodIds? }) * - webhooks.delete(webhookId) * * Events: message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified * Verify with Svix using webhook.secret. Use express.raw() for body—signature needs raw payload. */ import { AgentinboxClient } from "agentinbox"; import "dotenv/config"; const client = new AgentinboxClient({ apiKey: process.env.AGENTINBOX_API_KEY! }); async function main() { const wh = await client.webhooks.create({ url: "https://your-server.com/webhooks", eventTypes: ["message.received"], clientId: "my-webhook-v1", }); const allWh = await client.webhooks.list(); const secret = (await client.webhooks.get(wh.webhookId)).secret; } main(); ``` ## Дальше #### [События вебхуков](/events) Полный список типов событий и их полезных нагрузок. #### [Проверка вебхуков](/webhook-verification) Как проверять подписи вебхуков и защищать endpoints. #### [Пример: событийно-ориентированный агент](/webhook-agent) Развёртываемый агент, который отвечает на письма в реальном времени.