Перейти к основному содержанию
Вебхук — это HTTP-запрос, который Zenedu отправляет на ваш адрес, когда в аккаунте происходит определённое действие: оформлен заказ, подписчик получил тег, ответил на тест или написал боту. Вашей системе не нужно опрашивать API, чтобы узнать об изменениях: событие приходит само, обычно в течение нескольких секунд.

Как получать вебхуки

В Zenedu два способа отправить вебхук. Оба приходят в одном формате, подписываются одинаково и повторяются по одним правилам.

Быстрый старт

1

Создайте обработчик

Добавьте на свой сервер публичный HTTPS-адрес, который принимает POST-запросы с JSON-телом и отвечает статусом 2xx.
2

Добавьте вебхук

Откройте Настройки → Проект → API и вебхуки, в блоке Вебхуки нажмите Добавить, укажите адрес и выберите события. То же самое делает Создать вебхук.
3

Отправьте тест

Нажмите Отправить тест или вызовите Отправить тестовый вебхук. На адрес придёт событие webhook.test.
4

Проверяйте подпись

Прежде чем доверять запросу, проверьте подпись в заголовке Signature.

Формат запроса

Каждый вебхук — это POST-запрос с телом в JSON. Тело всегда одной формы: служебные поля и объект события в data.
Объекты в data совпадают с объектами API: подписчик — как в Получить подписчика, заказ — как в Получить заказ. Поля события, например tag_id и tag_name, лежат рядом с полями подписчика.

Заголовки

Подпись

Zenedu подписывает каждый вебхук. Заголовок Signature содержит HMAC-SHA256 от сырого тела запроса в шестнадцатеричном виде, ключ — API-токен аккаунта. Чтобы проверить запрос, вычислите HMAC от тела в том виде, в каком оно пришло, до разбора JSON, и сравните с заголовком:
После сброса API-токена вебхуки подписываются новым токеном.

Рекомендации

  • Отвечайте быстро. Верните 2xx в течение 3 секунд, а тяжёлую работу — запись в CRM, письма, запросы к API — выполняйте в фоновой очереди. Запрос, на который нет ответа за 3 секунды, считается неудачным и будет отправлен повторно.
  • Убирайте дубли. Одно событие может прийти больше одного раза. Сохраняйте _id обработанных доставок и пропускайте повторы.
  • Не полагайтесь на порядок. Каждый вебхук — отдельный HTTP-запрос, и из-за сетевых задержек или повторной попытки события, произошедшие почти одновременно, могут прийти в другом порядке. Если порядок важен, сравнивайте timestamp.
  • Подписывайтесь только на нужные события. Лишние события нагружают ваш сервер и не дают пользы.

Что дальше

Доставка и повторы

Расписание повторных попыток и автоотключение

Каталог событий

Все события и их данные

Вебхуки в API

Управление подписками через API