Настройка вебхуков | Agent Inbox

В этом руководстве вы настроите вебхуки для уведомлений от Agent Inbox в реальном времени: аккаунт ngrok, inbox, регистрация вебхука и простой приёмник на Python.

Требования

Перед началом убедитесь, что есть:

Python 3.8+
Ключ API Agent Inbox
менеджер пакетов pip
базовые навыки Python и терминала

Установка

$ pip install agentinbox flask ngrok

Шаг 1: Аккаунт ngrok

Ngrok поднимает безопасный туннель с публичного URL на ваш локальный сервер — Agent Inbox сможет слать вебхуки на вашу машину при разработке.

1.1 Регистрация

Зайдите на ngrok.com и зарегистрируйтесь.

1.2 Установка под вашу ОС

После входа ngrok подскажет установку под вашу систему.

На macOS через Homebrew:

$ brew install ngrok

Затем авторизация токеном из дашборда ngrok:

$ ngrok config add-authtoken YOUR_AUTHTOKEN

Шаг 2: Inbox в Agent Inbox

Нужен ящик для входящей почты. Создайте через API:

1 from agentinbox import Agentinbox
2 
3 client = Agentinbox()
4 
5 # Inbox для демо-агента вебхуков
6 inbox = client.inboxes.create(
7     username="webhook-demo",
8     client_id="webhook-demo-inbox"  # Идемпотентность
9 )
10 
11 print(f"Inbox created: {inbox.inbox_id}")

client_id гарантирует, что повторный запуск не создаст дубликат — вернётся существующий ящик.

Шаг 3: Регистрация вебхука в Agent Inbox

3.1 Запуск туннеля ngrok

В терминале (порт 3000):

$ ngrok http 3000

В выводе будет что-то вроде:

Скопируйте Forwarding URL (например https://your-subdomain.ngrok-free.app) — его укажете при регистрации вебхука.

Для просмотра в браузере — localhost

Для проверки страницы приёмника используйте http://127.0.0.1:3000 из строки Web Interface, а не URL ngrok. Ngrok нужен внешним сервисам вроде Agent Inbox.

Почему localhost? Safari строже Chrome/Firefox к dev-серверам через HTTPS-туннель ngrok: блокирует локальные WebSocket и часть скриптов, страница может «крутиться» из-за HMR. Это нормально для разработки. Localhost или статическая сборка обходят проблему.

3.2 Регистрация вебхука

1 # URL из ngrok
2 webhook_url = "https://your-subdomain.ngrok-free.app/webhooks"
3 
4 webhook = client.webhooks.create(
5     url=webhook_url,
6     event_types=["message.received"],  # при необходимости добавьте message.sent и др.
7     client_id="webhook-demo-webhook"  # Идемпотентность
8 )
9 
10 print(f"Webhook created: {webhook.webhook_id}")

Шаг 4: Пример приёма вебхуков

Файл webhook_receiver.py:

1 from flask import Flask, request, Response
2 
3 app = Flask(__name__)
4 
5 @app.route('/')
6 def home():
7     """Страница статуса"""
8     return """
9     <html>
10     <body style="font-family: sans-serif; max-width: 800px; margin: 50px auto; padding: 20px;">
11         <h1>Agent Inbox Webhook Receiver</h1>
12         <div style="background: #4CAF50; color: white; padding: 10px 20px;
13                     border-radius: 4px; display: inline-block; margin: 20px 0;">
14             Server is running
15         </div>
16         <div style="background: #e3f2fd; padding: 15px; border-radius: 4px;
17                     border-left: 4px solid #2196F3;">
18             <h3>Webhook Endpoint Ready</h3>
19             <p>Your webhook endpoint is listening at: <code>POST /webhooks</code></p>
20         </div>
21         <h3>How to use:</h3>
22         <ul>
23             <li>Start ngrok: <code>ngrok http 3000</code></li>
24             <li>Register your webhook with Agent Inbox using the ngrok URL</li>
25             <li>Send a test email to your Agent Inbox inbox</li>
26             <li>Watch the console for incoming webhook events</li>
27         </ul>
28     </body>
29     </html>
30     """
31 
32 @app.route('/webhooks', methods=['POST'])
33 def receive_webhook():
34     """Приём событий от Agent Inbox"""
35     payload = request.json
36 
37     event_type = payload.get('event_type')
38     message = payload.get('message', {})
39 
40     print(f"\nWebhook received: {event_type}")
41     print(f"From: {message.get('from_')}")
42     print(f"Subject: {message.get('subject')}\n")
43 
44     return Response(status=200)
45 
46 if __name__ == '__main__':
47     print("Starting webhook receiver on http://127.0.0.1:3000")
48     app.run(port=3000)

Запуск приёмника

Ngrok в одном терминале.
В другом:

$ python webhook_receiver.py

Отправьте тестовое письмо на inbox.
Смотрите вывод в консоли.

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

Откройте http://127.0.0.1:3000 — страница статуса.

Проверка настройки

Письмо на адрес ящика (например webhook-demo@agentinbox.space).
Консоль приёмника — должны появиться поля события.

Дальше

Расширьте receive_webhook():

автоответы
обработка вложений
маршрутизация по содержимому
связка с агентами

См. пример событийного агента.

Устранение неполадок

События не приходят

Ngrok запущен и URL совпадает с зарегистрированным вебхуком
Flask слушает нужный порт (3000)
URL вебхука заканчивается на /webhooks
Ошибки в консоли Flask и в веб-интерфейсе ngrok

Туннель ngrok обрывается

На бесплатном плане сессии ограничены (~2 часа). Перезапустите ngrok и обновите URL вебхука в Agent Inbox.

Порт занят

Выберите другой порт:

в app.run(port=XXXX)
в команде: ngrok http XXXX

Скопировать в Cursor / Claude

1 """
2 Agent Inbox Webhook Setup — copy into Cursor/Claude.
3 
4 Flow: 1) ngrok http 3000 → copy URL. 2) inboxes.create(client_id=...) 3) webhooks.create(url=ngrok+/webhooks, event_types=[...], client_id=...)
5 4) Flask POST /webhooks: return 200 immediately, process request.json in background.
6 Local: use http://127.0.0.1:3000 in browser, not ngrok URL.
7 """
8 from flask import Flask, request, Response
9 from agentinbox import Agentinbox
10 
11 app = Flask(__name__)
12 client = Agentinbox()
13 
14 inbox = client.inboxes.create(username="webhook-demo", client_id="webhook-demo-inbox")
15 wh = client.webhooks.create(url="https://YOUR_NGROK.ngrok-free.app/webhooks", event_types=["message.received"], client_id="webhook-demo-webhook")
16 
17 @app.route("/webhooks", methods=["POST"])
18 def receive():
19   payload = request.json
20   print(payload.get("event_type"), payload.get("message", {}).get("subject"))
21   return Response(status=200)

Продакшен

Отдельный сервер: облако (AWS, GCP, Heroku и т.д.), не ngrok.
Проверка подписи:проверяйте запросы.
Ошибки и ретраи: логирование, алерты.
Асинхронность: сразу 200, тяжёлую работу — в фон.
Догрузка через API: тело вебхука ограничено 1 МБ; при превышении поля text/html могут быть опущены. Полное письмо — через Get Message. Подробнее: лимит размера полезной нагрузки.
Мониторинг: логи и алерты по сбоям доставки.

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

Подписи Svix для безопасных эндпоинтов.

Обзор вебхуков

Как устроены вебхуки и структура payload.

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

Полный список типов событий.