Проверка вебхуков
Проверка вебхуков
Убедитесь, что запросы действительно от Agent Inbox.
При приёме вебхуков важно убедиться, что запрос пришёл от Agent Inbox и не был изменён. Доставка идёт через Svix с криптографической проверкой подписи.
Зачем проверять вебхуки?
Без проверки любой, кто узнает URL, может слать поддельные события:
- Подмена данных: ложные события запускают действия в вашей системе.
- Инциденты безопасности: вредоносные данные в потоке обработки.
- Исчерпание ресурсов: флуд фейковыми запросами.
В продакшене проверку подписи включайте всегда.
Секрет подписи
У каждого вебхука свой секрет. Его видно в консоли Agent Inbox при создании или в ответе API:
Храните секрет в безопасности
Держите секрет в переменных окружения или секрет-хранилище. Не коммитьте в репозиторий и не отдавайте в клиентский код.
Заголовки проверки
В каждом запросе от Agent Inbox есть три заголовка Svix:
Библиотека Svix (рекомендуется)
Проще всего — официальная библиотека Svix.
Нужно сырое тело
Проверка подписи требует точного тела запроса. Если используете парсер тела (express.json() и т.п.), для маршрута вебхука берите raw-тело или используйте express.raw().
Скопировать в Cursor / Claude
Локальная проверка с ngrok
Чтобы Agent Inbox достучался до локального сервера, нужен публичный URL. ngrok даёт туннель на вашу машину.
Шаг 1: Сохраните сервер
Шаг 2: Зависимости и запуск
Ожидаемый вывод:
Шаг 3: Запуск ngrok
Пример вывода:
Скопируйте HTTPS forwarding URL (например https://da550b82a183.ngrok.app).
Шаг 4: URL в консоли Agent Inbox
- Консоль Agent Inbox
- Раздел Webhooks
- Create Webhook (или редактирование)
- URL с путём
/webhooks, напримерhttps://da550b82a183.ngrok.app/webhooks - Выберите события, сохраните
- Секрет подписи в
.env:
Шаг 5: Тестовое событие
Отправьте письмо на один из inbox или тест из консоли. В терминале сервера должно появиться:
Продакшен
Ngrok удобен локально; в проде разверните сервер на хостинге со стабильным HTTPS. Варианты ниже.
Продакшен
Нужен стабильный публичный HTTPS и переменные окружения. Удобный старт — Render.
Рекомендации
В проде всегда проверяйте
Локально проверку можно ослабить, в продакшене — обязательно. Скомпрометированный вебхук — серьёзный риск.
Переменные окружения
Секрет не хардкодьте:
Устранение неполадок
Подпись не сходится
- Используйте сырое тело, не перепарсенное
- Секрет совпадает с эндпоинтом в консоли
- Заголовки читаются корректно (регистр не важен)
- Время в пределах допуска (по умолчанию около 5 минут)
Нет заголовков
Прокси или фреймворк могут отрезать кастомные заголовки — проверьте настройки reverse proxy.
Парсинг тела
Для Express на маршруте вебхука используйте express.raw().
