Обзор вебхуков | Agent Inbox

Вебхуки — самый удобный способ получать информацию о том, что происходит с вашей почтой, в реальном времени. Вместо постоянных запросов к API Agent Inbox, есть ли новое письмо (так называемый polling), вы регистрируете URL, и мы отправляем вам POST с подробностями сразу после события.

Такой событийный подход эффективнее и позволяет строить быстрых, отзывчивых агентов, которые мгновенно реагируют на входящие сообщения.

Зачем нужны вебхуки?

Скорость в реальном времени: диалоговые агенты могут отвечать на входящие письма за секунды.
Эффективность: не нужен постоянный polling — экономятся ресурсы и упрощается логика приложения.

Доступные события

Agent Inbox поддерживает семь типов событий вебхуков. При создании вебхука можно подписаться на отдельные типы или на все сразу. Полное описание полезной нагрузки — в разделе События вебхуков.

События сообщений:

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 и типы событий, которые хотите получать.

1 client.webhooks.create(
2     url="https://<your-ngrok-url>.ngrok-free.app/webhooks",
3     event_types=["message.received", "message.sent"],
4 )

Укажите нужные события; опустите event_types, чтобы подписаться на все типы.

3. Agent Inbox отправляет события

Когда происходит событие (например, пришло новое письмо, доставка подтверждена или домен верифицирован), Agent Inbox отправляет POST с JSON на зарегистрированный URL.

Структура полезной нагрузки

В вебхуке есть event_type и event_id, плюс данные, зависящие от типа события. Ниже пример для message.received; у других событий другие объекты верхнего уровня (send, delivery, bounce и т. д.). Форму полезной нагрузки для каждого события см. в Событиях вебхуков.

Ограничение размера полезной нагрузки

Размер полезной нагрузки вебхука ограничен 1 МБ. Если сообщение больше, Agent Inbox убирает из полезной нагрузки поля text и html, чтобы уменьшить размер. Остальные метаданные сохраняются. Встроенные в HTML картинки (в том числе data URI в base64) учитываются в размере и часто приводят к достижению лимита.

Пропущенное содержимое всегда можно получить через API. После вебхука загрузите полное сообщение, чтобы получить тело и вложения:

1 # fetch the full message after receiving a webhook
2 message = client.inboxes.messages.get(
3     inbox_id=payload["message"]["inbox_id"],
4     message_id=payload["message"]["message_id"],
5 )
6 text_body = message.text
7 html_body = message.html

Webhook Payload

1 {
2   "event_type": "message.received",
3   "event_id": "evt_123abc...",
4   "message": {
5     "from_": ["sender@example.com"],
6     "organization_id": "org_abc123...",
7     "inbox_id": "inbox_def456...",
8     "thread_id": "thd_ghi789...",
9     "message_id": "<jkl012@agentinbox.space>",
10     "labels": ["received"],
11     "timestamp": "2023-10-27T10:00:00Z",
12     "reply_to": ["reply-to@example.com"],
13     "to": ["recipient@example.com"],
14     "cc": ["cc-recipient@example.com"],
15     "bcc": ["bcc-recipient@example.com"],
16     "subject": "Email Subject",
17     "preview": "A short preview of the email text...",
18     "text": "The full text body of the email.",
19     "html": "<html>...</html>",
20     "attachments": [
21       {
22         "attachment_id": "att_pqr678...",
23         "filename": "document.pdf",
24         "content_type": "application/pdf",
25         "size": 123456,
26         "inline": false
27       }
28     ],
29     "in_reply_to": "<parent456@agentinbox.space>",
30     "references": ["<ref001@agentinbox.space>", "<ref002@agentinbox.space>"],
31     "sort_key": "some-sort-key",
32     "updated_at": "2023-10-27T10:00:05Z",
33     "created_at": "2023-10-27T10:00:00Z"
34   }
35 }

Описание полей

event_type (string): тип события (например message.received, message.sent, message.delivered). Структура полезной нагрузки зависит от типа — см. События вебхуков.
event_id (string): уникальный идентификатор этой доставки события.
message (object): словарь с полными данными полученного письма.
- from_ (array<string>): адрес отправителя. Подчёркивание в конце — чтобы не конфликтовать с ключевым словом Python.
- organization_id (string): идентификатор вашей организации.
- inbox_id (string): идентификатор ящика, куда пришло письмо.
- thread_id (string): идентификатор цепочки (треда).
- message_id (string): уникальный идентификатор этого сообщения.
- labels (array<string>): метки сообщения (например received, sent).
- subject (string): тема письма.
- preview (string): короткий текстовый превью тела.
- text (string): тело в виде plain text. Может отсутствовать при превышении лимита 1 МБ. Если поля нет — загрузите сообщение через API.
- html (string): HTML-тело, если есть. Может отсутствовать при превышении лимита 1 МБ. Если поля нет — загрузите сообщение через API.
- attachments (array<object>): метаданные вложений (attachment_id, filename, content_type, size, inline). Содержимое вложений в вебхук не входит — скачивайте через API.
- in_reply_to (string): message_id письма, на которое это ответ, если применимо.

Копировать в Cursor / Claude

Скопируйте один из блоков ниже в Cursor или Claude, чтобы за один раз передать полное описание API вебхуков.

1 """
2 Agent Inbox Webhooks — copy into Cursor/Claude.
3 
4 Setup: pip install agentinbox python-dotenv. Set AGENTINBOX_API_KEY in .env.
5 Return 200 immediately; process payload in background.
6 
7 API reference:
8 - webhooks.create(url, event_types?, inbox_ids?, pod_ids?, client_id?)
9 - webhooks.get(webhook_id), webhooks.list(limit?, page_token?)
10 - webhooks.update(webhook_id, add_inbox_ids?, remove_inbox_ids?, add_pod_ids?, remove_pod_ids?)
11 - webhooks.delete(webhook_id)
12 
13 Events: message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified
14 Payload: event_type, event_id, plus message/send/delivery/bounce/complaint/reject/domain. Verify with Svix (webhook.secret).
15 """
16 import os
17 from dotenv import load_dotenv
18 from agentinbox import Agentinbox
19 
20 load_dotenv()
21 client = Agentinbox(api_key=os.getenv("AGENTINBOX_API_KEY"))
22 
23 wh = client.webhooks.create(url="https://your-server.com/webhooks", event_types=["message.received"], client_id="my-webhook-v1")
24 all_wh = client.webhooks.list()
25 secret = client.webhooks.get(wh.webhook_id).secret

Дальше

События вебхуков

Полный список типов событий и их полезных нагрузок.

Проверка вебхуков

Как проверять подписи вебхуков и защищать endpoints.

Пример: событийно-ориентированный агент

Развёртываемый агент, который отвечает на письма в реальном времени.