Webhooks: события о сообщениях

Что делает

Виджет присылает на адрес вашей системы уведомление о каждом новом сообщении в чатах Авито. Адрес вы указываете сами. Приходит всё: вопросы покупателей, ответы менеджеров из amoCRM, сообщения, отправленные через API, автоответы виджета, ответы из приложения Авито, системные сообщения и звонки. Так к переписке подключают AI-помощника, свою CRM, отчёты или чат-бота.

Работает на тарифе «Профессиональный». На «Стандартном» в блоке будет надпись «Доступно в тарифе «Профессиональный»» и кнопка «Связаться с поддержкой».

Эта статья для владельца аккаунта: как завести подписку и следить, что события доходят. Как проверять подпись и разбирать событие, описано в инструкции для AI-агента и разработчика.

Как настроить

1. Откройте виджет и в верхнем меню нажмите вкладку «API».
2. В блоке «Webhooks» нажмите «Добавить подписку». Откроется окно «Новая подписка».
3. «URL вашего сервера» — адрес, куда слать события. Только https://, доменное имя (не IP-адрес), и сервер должен быть доступен из интернета. Адрес вам даст разработчик или сервис, который будет принимать события.
4. «Название» — любое, чтобы узнать подписку в списке. Например, «AI-квалификатор».
5. «События» — какие сообщения присылать. По умолчанию отмечены все три:
   • Входящие — сообщения покупателей;
   • Исходящие — ответы менеджеров, автоответы, отправка через API и из приложения Авито;
   • Системные — уведомления Авито и звонки.
6. «Токен X-Webhook-Token» — необязательное поле. Токен приходит в каждом запросе, по нему ваш сервер узнаёт, что запрос от нас. Нажмите «Сгенерировать» или впишите свой. После сохранения токен больше не показывается, скопируйте его сразу.

7. Нажмите «Создать». Виджет проверит адрес.
8. Откроется окно «Подписка создана» с секретом подписи. Секрет показывается один раз: нажмите «Копировать», передайте его разработчику и только потом нажмите «Я сохранил секрет».

9. В карточке подписки нажмите «Тест». На ваш адрес уйдёт проверочный запрос, а в карточке появится результат, например «Тест: Доставлено: HTTP 200 · 0.3 с»: код ответа вашего сервера и за сколько секунд он ответил.

Что видно в карточке подписки

• Название, адрес и выбранные события. Пометка «с токеном», если токен задан.
• Статус: «Активна», «Есть ошибки», «На паузе», «Выключена» (вы выключили сами) или «Отключена» (отключилась автоматически).
• «Последняя успешная доставка». Если есть ошибки, то и «Последняя ошибка»: что случилось и сколько раз подряд.

Кнопки карточки:

• «Тест» — проверочный запрос на ваш адрес. Не чаще раза в 10 секунд.
• «Журнал доставок» — что и когда отправили (см. ниже).
• «Изменить» — поменять адрес, название, события или токен.
• «Новый секрет» — выпустить новый секрет подписи, если старый потерян или утёк. Старый секрет работает ещё 24 часа, чтобы разработчик успел заменить его у себя.
• «Выключить» — остановить отправку, не удаляя подписку. События за это время копятся.
• «Включить» — появляется у выключенной или отключённой подписки.
• «Удалить» — удаляет подписку вместе с журналом доставок. Отменить нельзя.

Баннеры: что они значат и что делать.

• «Сервер не принимает запросы — отправка на паузе до …» — несколько ошибок подряд, отправка приостановлена и после паузы продолжится сама. Проверьте свой сервер.
• «Сервер не отвечал 3 суток — подписка отключена автоматически» — почините сервер и нажмите «Включить».
• «Сервер ответил 410 Gone — подписка отключена автоматически» — ваш сервер сообщил, что адреса больше нет. Проверьте адрес и включите подписку.
• «Адрес недопустим: домен указывает на внутренний или локальный адрес» — нажмите «Изменить» и укажите публичный адрес.
• «Виджет переустановлен — подтвердите подписку, включив её снова» — после переустановки виджета подписки выключаются. Это защита: включите их вручную.
• «Подписка создана или её адрес изменён через API-ключ» — подписку завёл не человек в виджете, а программа по ключу. Если это были не вы, удалите подписку и отзовите ключи с правом «Управление webhook-подписками».
• «Идёт смена секрета: старый секрет действует до …» — после нажатия «Новый секрет». Ничего делать не нужно, если разработчик уже поменял секрет.
• «Отправка приостановлена: подписка» — у виджета закончилась подписка или сменился тариф. События не отправляются, после продления «Профессионального» уйдёт накопленное за последние 48 часов.
• «Функция временно недоступна» или «Функция временно приостановлена» — работы на нашей стороне. Подписки сохранены, выключить или удалить их можно, а менять нельзя. Попробуйте позже.
• «Отправка событий на ваши серверы временно приостановлена с нашей стороны» — события сохраняются и уйдут после возобновления.

Журнал доставок.

1. В карточке подписки нажмите «Журнал доставок».
2. В списке видно: событие, чат, статус, число попыток, результат и время. Статусы: «В очереди», «Отправляется», «Доставлено», «Не доставлено», «Удержано». Фильтр «Статус» оставляет только нужные, кнопка «Обновить» перечитывает список.
3. Нажмите на номер строки, чтобы увидеть, что именно отправили.
4. «Переотправить» в строке отправляет одно событие ещё раз.
5. Чтобы повторить все неудачные сразу, укажите дату в поле «Недоставленные начиная с» и нажмите «Переотправить все неудачные».

Включение после отключения.

1. В карточке подписки нажмите «Включить».
2. Выберите, что делать с событиями, которые накопились, пока подписка не работала:
   • «Отправить накопленное за последние 48 часов» — они уйдут на ваш сервер, более старые будут отмечены как недоставленные;
   • «Сбросить накопленное и начать с новых событий» — накопленное помечается недоставленным, его можно переотправить из журнала в течение 6 суток.
3. Нажмите «Включить», затем «Тест», чтобы убедиться, что сервер принимает запросы.

Ограничения и частые вопросы

• Сколько подписок можно завести? До трёх на аккаунт. Например, одна для AI-помощника, другая для своей CRM.
• Как быстро приходят события? Обычно через 1–2 секунды после сообщения. Первое сообщение в новом чате приходит позже, до 20 секунд: виджет ждёт, пока в amoCRM создадутся чат и сделка, чтобы сразу прислать их в событии. Голосовое сообщение приходит примерно через 10 секунд.
• Что должен ответить сервер? Любой успешный код (2xx) за 5 секунд. Если сервер не успел, это считается ошибкой.
• Что если сервер не отвечает? Виджет повторяет отправку с растущими паузами около 46 часов. После 5 ошибок подряд отправка на адрес ставится на паузу. Если адрес не отвечает 72 часа, подписка отключается и в виджете появляется баннер.
• Сколько хранится журнал? Доставленные события — 3 дня, остальные — 7 дней. Переотправить можно события не старше 6 суток, не больше 1000 в час на подписку. Ответ вашего сервера не сохраняется.
• Редиректы не поддерживаются. Если адрес переадресует на другой, доставка считается ошибкой. Укажите конечный адрес.
• Одно сообщение может прийти дважды? Да, при повторах. Разработчик отсеивает дубли по номеру события, это описано в инструкции.
• Приходят ли системные сообщения, которые скрыты настройками виджета? Да, приходят все. Отфильтровать лишнее ваша система может сама.
• Что будет, когда закончится подписка на виджет? События перестанут уходить и начнут копиться. После оплаты автоматически отправится накопленное за последние 48 часов.
• Все ли сообщения дойдут? Почти все. Сам Авито иногда теряет уведомления, это доли процента. Для сверки есть API истории переписки: разработчик может раз в час сверять и добирать пропущенное.
• Сервер долго лежал, а очередь переполнилась? В очереди подписки держится до 5000 неотправленных событий. Остальное разработчик заберёт через API истории.
• Персональные данные. В событиях есть имя покупателя, текст переписки и номера сделки и контакта. Адрес, куда всё это уходит, выбираете вы, и обработка данных на вашей стороне — ваша ответственность.
• Это не действие «Вебхук». Действие «Вебхук» в сценариях Авито Доставки шлёт запрос при смене статуса заказа. Эта подписка присылает сообщения из чатов.

Связанные разделы

• API для интеграций
• API-ключи и отправка сообщений
• Подключение AI-агента
• Подписка и тарифы
• Действие «Вебхук» (статусы заказа Доставки)
• Журнал событий