Webhooks: события о сообщениях
Что делает. Виджет присылает на адрес вашей системы уведомление о каждом новом сообщении в чатах Авито. Адрес вы указываете сами. Приходит всё: вопросы покупателей, ответы менеджеров из amoCRM, сообщения, отправленные через API, автоответы виджета, ответы из приложения Авито, системные сообщения и звонки. Так к переписке подключают AI-помощника, свою CRM, отчёты или чат-бота.
Работает на тарифе «Профессиональный». На «Стандартном» в блоке будет надпись «Доступно в тарифе «Профессиональный»» и кнопка «Связаться с поддержкой».
Эта статья для владельца аккаунта: как завести подписку и следить, что события доходят. Как проверять подпись и разбирать событие, описано в инструкции для AI-агента и разработчика.
Как настроить.
- Откройте виджет и в верхнем меню нажмите вкладку «API».
- В блоке «Webhooks» нажмите «Добавить подписку». Откроется окно «Новая подписка».
- «URL вашего сервера» — адрес, куда слать события. Только
https://, доменное имя (не IP-адрес), и сервер должен быть доступен из интернета. Адрес вам даст разработчик или сервис, который будет принимать события. - «Название» — любое, чтобы узнать подписку в списке. Например, «AI-квалификатор».
- «События» — какие сообщения присылать. По умолчанию отмечены все три:
- Входящие — сообщения покупателей;
- Исходящие — ответы менеджеров, автоответы, отправка через API и из приложения Авито;
- Системные — уведомления Авито и звонки.
- «Токен X-Webhook-Token» — необязательное поле. Токен приходит в каждом запросе, по нему ваш сервер узнаёт, что запрос от нас. Нажмите «Сгенерировать» или впишите свой. После сохранения токен больше не показывается, скопируйте его сразу.
- Нажмите «Создать». Виджет проверит адрес.
- Откроется окно «Подписка создана» с секретом подписи. Секрет показывается один раз: нажмите «Копировать», передайте его разработчику и только потом нажмите «Я сохранил секрет».
- В карточке подписки нажмите «Тест». На ваш адрес уйдёт проверочный запрос, а в карточке появится результат, например «Тест: Доставлено: HTTP 200».
Что видно в карточке подписки.
- Название, адрес и выбранные события. Пометка «с токеном», если токен задан.
- Статус: «Активна», «Есть ошибки», «На паузе», «Выключена» (вы выключили сами) или «Отключена» (отключилась автоматически).
- «Последняя успешная доставка». Если есть ошибки, то и «Последняя ошибка»: что случилось и сколько раз подряд.
Кнопки карточки:
- «Тест» — проверочный запрос на ваш адрес. Не чаще раза в 10 секунд.
- «Журнал доставок» — что и когда отправили (см. ниже).
- «Изменить» — поменять адрес, название, события или токен.
- «Новый секрет» — выпустить новый секрет подписи, если старый потерян или утёк. Старый секрет работает ещё 24 часа, чтобы разработчик успел заменить его у себя.
- «Выключить» — остановить отправку, не удаляя подписку. События за это время копятся.
- «Включить» — появляется у выключенной или отключённой подписки.
- «Удалить» — удаляет подписку вместе с журналом доставок. Отменить нельзя.
Баннеры: что они значат и что делать.
- «Сервер не принимает запросы — отправка на паузе до …» — несколько ошибок подряд, отправка приостановлена и после паузы продолжится сама. Проверьте свой сервер.
- «Сервер не отвечал 3 суток — подписка отключена автоматически» — почините сервер и нажмите «Включить».
- «Сервер ответил 410 Gone — подписка отключена автоматически» — ваш сервер сообщил, что адреса больше нет. Проверьте адрес и включите подписку.
- «Адрес недопустим: домен указывает на внутренний или локальный адрес» — нажмите «Изменить» и укажите публичный адрес.
- «Виджет переустановлен — подтвердите подписку, включив её снова» — после переустановки виджета подписки выключаются. Это защита: включите их вручную.
- «Подписка создана или её адрес изменён через API-ключ» — подписку завёл не человек в виджете, а программа по ключу. Если это были не вы, удалите подписку и отзовите ключи с правом «Управление webhook-подписками».
- «Идёт смена секрета: старый секрет действует до …» — после нажатия «Новый секрет». Ничего делать не нужно, если разработчик уже поменял секрет.
- «Отправка приостановлена: подписка» — у виджета закончилась подписка или сменился тариф. События не отправляются, после продления «Профессионального» уйдёт накопленное за последние 48 часов.
- «Функция временно недоступна» или «Функция временно приостановлена» — работы на нашей стороне. Подписки сохранены, выключить или удалить их можно, а менять нельзя. Попробуйте позже.
- «Отправка событий на ваши серверы временно приостановлена с нашей стороны» — события сохраняются и уйдут после возобновления.
Журнал доставок.
- В карточке подписки нажмите «Журнал доставок».
- В списке видно: событие, чат, статус, число попыток, результат и время. Статусы: «В очереди», «Отправляется», «Доставлено», «Не доставлено», «Удержано». Фильтр «Статус» оставляет только нужные, кнопка «Обновить» перечитывает список.
- Нажмите на номер строки, чтобы увидеть, что именно отправили.
- «Переотправить» в строке отправляет одно событие ещё раз.
- Чтобы повторить все неудачные сразу, укажите дату в поле «Недоставленные начиная с» и нажмите «Переотправить все неудачные».
Включение после отключения.
- В карточке подписки нажмите «Включить».
- Выберите, что делать с событиями, которые накопились, пока подписка не работала:
- «Отправить накопленное за последние 48 часов» — они уйдут на ваш сервер, более старые будут отмечены как недоставленные;
- «Сбросить накопленное и начать с новых событий» — накопленное помечается недоставленным, его можно переотправить из журнала в течение 6 суток.
- Нажмите «Включить», затем «Тест», чтобы убедиться, что сервер принимает запросы.
Ограничения и частые вопросы.
- Сколько подписок можно завести? До трёх на аккаунт. Например, одна для AI-помощника, другая для своей CRM.
- Как быстро приходят события? Обычно через 1–2 секунды после сообщения. Первое сообщение в новом чате приходит позже, до 20 секунд: виджет ждёт, пока в amoCRM создадутся чат и сделка, чтобы сразу прислать их в событии. Голосовое сообщение приходит примерно через 10 секунд.
- Что должен ответить сервер? Любой успешный код (2xx) за 5 секунд. Если сервер не успел, это считается ошибкой.
- Что если сервер не отвечает? Виджет повторяет отправку с растущими паузами около 46 часов. После 5 ошибок подряд отправка на адрес ставится на паузу. Если адрес не отвечает 72 часа, подписка отключается и в виджете появляется баннер.
- Сколько хранится журнал? Доставленные события — 3 дня, остальные — 7 дней. Переотправить можно события не старше 6 суток, не больше 1000 в час на подписку. Ответ вашего сервера не сохраняется.
- Редиректы не поддерживаются. Если адрес переадресует на другой, доставка считается ошибкой. Укажите конечный адрес.
- Одно сообщение может прийти дважды? Да, при повторах. Разработчик отсеивает дубли по номеру события, это описано в инструкции.
- Приходят ли системные сообщения, которые скрыты настройками виджета? Да, приходят все. Отфильтровать лишнее ваша система может сама.
- Что будет, когда закончится подписка на виджет? События перестанут уходить и начнут копиться. После оплаты автоматически отправится накопленное за последние 48 часов.
- Все ли сообщения дойдут? Почти все. Сам Авито иногда теряет уведомления, это доли процента. Для сверки есть API истории переписки: разработчик может раз в час сверять и добирать пропущенное.
- Сервер долго лежал, а очередь переполнилась? В очереди подписки держится до 5000 неотправленных событий. Остальное разработчик заберёт через API истории.
- Персональные данные. В событиях есть имя покупателя, текст переписки и номера сделки и контакта. Адрес, куда всё это уходит, выбираете вы, и обработка данных на вашей стороне — ваша ответственность.
- Это не действие «Вебхук». Действие «Вебхук» в сценариях Авито Доставки шлёт запрос при смене статуса заказа. Эта подписка присылает сообщения из чатов.