Как настроить вебхуки

Вебхук передаёт данные ответа из WebAsk на ваш сервер или в сервис, который умеет принимать HTTP-запросы. Например, получатель может создать заявку в CRM после отправки анкеты.

Сначала подготовьте публичный HTTP(S)-адрес приёмника и узнайте его требования: метод запроса, заголовки и обработку JSON. Адрес localhost на вашем компьютере не подходит для обращения с сервера WebAsk.

Для записи в своей CRM или 1С:Документооборот подготовьте принимающий обработчик. Он должен сопоставить поля JSON с полями вашей системы и создать либо обновить нужную запись. Заранее выберите ключ поиска, например номер заказа. У готового подключения Битрикс24 отдельная настройка.

SMS со ссылкой на опрос отправляйте через свою CRM или SMS-сервис: там настраиваются получатель, текст и момент отправки. После заполнения анкеты её данные можно вернуть вебхуком и связать с исходной записью по выбранному ключу.

Как создать вебхук

1. Откройте опрос → «Интеграции» → «Вебхуки».
2. Нажмите «Создать вебхук», а если записи уже есть: «Создать новый вебхук».
3. Укажите название и «URL обратного вызова»: адрес приёмника, а не ссылку на опрос.
4. Выберите «Тип запроса»: GET, POST, PUT или PATCH по требованиям получателя. Формат данных: JSON. Даже при выборе GET данные идут в JSON-теле запроса, а не в параметрах URL.
5. При необходимости заполните пары «Название заголовка» / «Значение». Кнопка «+ Добавить строку» добавляет ещё одну пару.

Увеличить

Какие данные отправлять

В разделе «Вопросы» выберите поля, которые нужны получателю. Если в опросе есть скрытые переменные, их также можно включить. Состав выбранных полей виден в блоке «Предпросмотр ответа».

«Названия параметров» позволяют добавить понятное имя вопроса, например «Имя» или «Оценка». Оно попадёт в свойство name объекта вопроса; ключом в JSON останется UUID. Это не переименование всех ключей запроса.

Переключатель «Отправлять незавершенные ответы» добавляет периодическую передачу незавершённых анкет. В списке «Отправлять каждые» доступны 1, 6, 12 и 24 часа. Это период обработки, а не обещание доставки ровно через столько часов после ухода каждого участника.

Увеличить

Как связать запрос с ответом WebAsk

В JSON есть answer_id: идентификатор ответа, log_id: идентификатор отправки и is_complete: признак завершённой анкеты. Также передаются служебные данные, баллы и выбранные поля вопросов. Формат значения зависит от типа вопроса: файл, матрица и обычный текст устроены по-разному.

Одна анкета может сначала прийти незавершённой, затем завершённой; возможна и повторная доставка. На стороне получателя учитывайте answer_id, чтобы обновлять нужную запись и не создавать дубль при каждом запросе.

Как сохранить и включить

1. Нажмите «Сохранить». WebAsk вернёт вас в список вебхуков.
2. Включите переключатель у нужного адреса: новая запись изначально выключена.
3. Если опрос ещё не опубликован, опубликуйте его, чтобы получить обычную ссылку для ответов. В уже опубликованном опросе вебхук начинает работать после сохранения и включения: новый выпуск для этого не нужен.

Чтобы изменить параметры, откройте меню с тремя точками → «Редактировать». В том же меню есть «Логи» и «Удалить». Удаление вебхука удаляет и его журнал, поэтому для исправления адреса или заголовка лучше отредактировать запись.

Увеличить

Как проверить передачу

Откройте меню нужного вебхука → «Логи». На странице журнала есть кнопка «Тестовый запрос»: она действительно отправляет искусственные данные получателю, даже если вебхук выключен. Используйте её только для подготовленного приёмника.

Тестовый запрос включает все вопросы и не подтверждает точный состав рабочей передачи с выбранными полями. Затем отправьте ответ по обычной ссылке опроса и сопоставьте данные в журнале с записью у получателя.

Пример: ответ получен, но сервер вернул ошибку

В этом примере в анкете указаны «Имя»: Анна и «Оценка»: 5. Вебхук отправил оба поля методом POST на отдельный приёмник Webhook.site. Для такого временного приёмника используйте только искусственные данные.

Приёмник получил запрос, но вернул HTTP 400 и сообщение {"error":"Учебная ошибка"}. Поэтому в WebAsk запись попала в «Не дошли»: получение запроса сервером и успешная обработка различаются.

Увеличить

Откройте запись. В деталях видны причина ошибки, ответ сервера, метод POST и ссылка на ответ WebAsk. В нашем примере это ответ 10378514 и запрос 2336717.

Увеличить

Какие поля пришли в JSON

Это поля фактически полученного запроса. Остальные служебные поля здесь опущены.

• answer_id: 10378514.
• log_id: 2336717.
• is_complete: true, анкета завершена.

Вопрос с ключом 6dc55efc-e848-4b1b-aaf9-769fd40d5512:

• name: «Имя»; results.result: «Анна».

Вопрос с ключом b68f8e4a-b56d-40da-845b-3d7db57131cd:

• name: «Оценка»; results.result: «5».

Ключи UUID и номера у вашего опроса будут другими. Даже для числового вопроса в этом запросе значение «5» передано строкой.

Увеличить

Как читать журнал и повторить запрос

Используйте вкладки «Все», «Не дошли» и «Дошли». Нажмите «Обновить», затем откройте нужную запись: в деталях доступны данные запроса и ответа, HTTP-код или описание ошибки.

• Код 2xx. Сервер принял HTTP-запрос. Дополнительно убедитесь, что система создала или обновила нужную запись.
• Код 4xx. Проверьте адрес, метод, авторизацию и формат, который ожидает приёмник.
• Код 5xx. Проверьте ошибку на стороне сервера получателя.
• Нет HTTP-кода. Проверьте описание сетевой ошибки: например, DNS, TLS, недоступное соединение или превышение времени ожидания.

Сначала исправьте причину ошибки. Затем откройте неудачную запись → «Отправить снова». В нашем примере приёмник после исправления вернул HTTP 200 и {"ok":true}. Та же запись 2336717 получила статус «Дошло»: в журнале стало «Не дошли: 0», «Дошли: 1». Новая строка для этого повтора не создавалась.

После повтора обновите журнал и сопоставьте данные с запросом у получателя. Сначала может отображаться очередь; дождитесь итогового статуса.

Увеличить

Для нескольких недошедших запросов используйте «Отправить снова» над списком и выберите период: за всё время, сегодня, неделю или месяц. Для повтора применяются текущие заголовки и настройки выбранных полей: это не обязательно побайтная копия старого запроса.