Webhooks

Вебхук — это отправка данных на адрес при выполнении какого-либо события. В нашем случае это отправка ответа на опрос. Вебхуки предназначены для продвинутых пользователей обладающих знаниями программирования.

Как подключить

Для подключения вебхуков перейдите во вкладку «Интеграции» → «Вебхуки» и кликните на «Подключить».

Скачайте markdown‑версию раздела «Webhooks» для использования в ChatGPT / других LLM:

AI Markdown

/static/api/webhooks.md

AI Markdown

Интерфейс настройки webhooks

Шаг 1: Переход в раздел интеграций

Для подключения вебхуков перейдите во вкладку «Интеграции» → «Вебхуки» и кликните на «Подключить».

Шаг 2: Форма настройки webhook

После этого у вас откроется экран где необходимо указать название вебхука, URL обратного вызова и тип запроса.

Шаг 3: Тестирование webhook

Проверить работу вебхука вы можете с помощью https://webhook.site

Шаг 4: Просмотр логов

Либо же просмотрев логи в интерфейсе WebAsk

Настройки вебхука

В форме настройки вебхука доступны следующие параметры:

Параметр	Описание
Название	Произвольное имя для идентификации вебхука в списке
URL	Адрес вашего endpoint'а. WebAsk отправляет на него `POST`-запрос при каждом новом ответе
Заголовки	Произвольные HTTP-заголовки в формате «ключ: значение». Отправляются с каждым запросом и дублируются в поле `headers` тела payload для удобства логирования
Включён	Переключатель активности. Выключенный вебхук не отправляет запросы, но сохраняет все настройки

Секретный токен через заголовок

Добавьте заголовок Authorization: Bearer ваш-секрет — ваш сервер сможет проверять, что запрос действительно пришёл от WebAsk.

Когда срабатывают webhooks

В WebAsk webhooks срабатывают при отправке ответа на опрос. Это основное событие, которое можно отслеживать.

Событие: Ответ на опрос

Webhook срабатывает каждый раз, когда пользователь отправляет ответ на ваш опрос. Это позволяет получать уведомления в реальном времени о новых ответах.

Автоматическая отправка

Webhook отправляется автоматически сразу после получения ответа на опрос

Формат payload

WebAsk отправляет POST-запрос с телом в формате JSON. Ниже описана полная структура тела запроса.

Поля в корне payload

Поле	Тип	Описание
headers	object	Заголовки, настроенные в вебхуке. Дублируются в body для удобства логирования и отладки
extra_params	object / array	Скрытые переменные и UTM-метки, переданные при прохождении опроса. Пустой массив `[]`, если переменных нет
promo_code	string / null	Промокод, использованный при прохождении опроса, или `null`
log_id	int	ID записи лога отправки этого вебхука
score_all	int	Максимально возможный балл за весь опрос. `0`, если скоринг не настроен
score_earned	int	Суммарный балл, набранный респондентом
score_percent	float / null	Процент результата: `(score_earned / score_all) × 100`, округление до 1 знака. `null`, если `score_all = 0`
scores	object	Сводка баллов: поля `user`, `max` и `by_question` — карта `{ "uuid": int \| null }`
{question_uuid}	object	Ответ на вопрос с данным UUID. На каждый вопрос в опросе — отдельный ключ верхнего уровня

Поля объекта вопроса

Каждый вопрос в payload — объект с UUID вопроса в качестве ключа. Все типы вопросов содержат следующие общие поля:

Поле	Тип	Описание
title	string	Текст вопроса (заголовок виджета)
type	string	Тип виджета: `choiceSingle`, `choiceMultiple`, `rating`, `matrix` и др.
question_uuid / uuid	string	UUID вопроса (дублируется внутри объекта)
results	object / array	Ответ респондента. Формат зависит от типа виджета — см. раздел ниже
score_count	int / null	Балл, набранный за этот вопрос. `null`, если скоринг к типу не применяется
score_max	int / null	Максимальный балл за этот вопрос. `null`, если скоринг не применяется
is_correct_question	bool / null	Итоговая корректность ответа: `true` — правильно, `false` — нет, `null` — не применимо
other	string	Текст варианта «Другое», если был выбран (для choice-виджетов). Пустая строка, если не выбран
inline_group_id	string / null	UUID группы вопросов, если вопрос входит в группу
inline_group_title	string / null	Название группы вопросов
is_inline_group_child	bool	`true`, если вопрос находится внутри группы

Формат `results` по типу виджета

Поле results имеет разный формат в зависимости от типа вопроса.

choiceSingle, choiceMultiple, yesno, dropdown

Массив выбранных вариантов. Каждый элемент содержит текст варианта, балл и признак корректности.

{
  "results": [
    {
      "result": "Вариант А",
      "score": 10,
      "is_correct": true
    }
  ]
}

choiceMedia

Массив выбранных вариантов с медиа. В поле result передаётся URL изображения выбранного варианта.

{
  "results": [
    {
      "result": "https://app.webask.io/.../image.png",
      "score": 3,
      "is_correct": false
    }
  ]
}

ranking

Массив вариантов в порядке расстановки пользователем (первый элемент — поставлен на 1-е место). Скоринг и корректность для этого типа не применяются.

{
  "results": [
    { "result": "Первое место",  "score": null, "is_correct": null },
    { "result": "Второе место", "score": null, "is_correct": null },
    { "result": "Третье место",  "score": null, "is_correct": null }
  ]
}

rating

Объект (не массив). Поле is_star: true — режим «звёзды/сердца»; score_num: false — не числовой режим отображения.

{
  "results": {
    "result": "4",
    "is_star": true,
    "score": 0,
    "score_num": false,
    "is_correct": false
  }
}

scale

Объект с выбранным значением на шкале, баллом и корректностью.

{
  "results": {
    "result": "6",
    "score": 0,
    "is_correct": true
  }
}

slider

Объект только со значением. Скоринг для ползунка не применяется.

{
  "results": {
    "result": "45"
  }
}

input, email, phone

Объект с введённым значением. Скоринг не применяется. Для многострочного ввода переносы строк сохраняются.

{
  "results": {
    "result": "Текст ответа пользователя"
  }
}

datetime

Объект с датой/временем. Формат значения зависит от режима виджета.

// Дата + время
{ "results": { "result": "12.03.2026 21:12" } }

// Только дата
{ "results": { "result": "11.03.2026" } }

// Только время
{ "results": { "result": "18:14" } }

file

Массив загруженных файлов. Каждый элемент содержит URL для скачивания и расширение файла.

{
  "results": [
    {
      "result": "https://app.webask.io/.../document.pdf",
      "file_ext": "pdf"
    }
  ]
}

matrix

Наиболее сложный тип. Содержит два представления:
— results — человекочитаемый вид: вложенный объект { "строка": { "колонка": { result, score, is_correct } } }. Значение result: "1" — ячейка отмечена, result: "" — нет.
— answers — машинный вид по UUID: { "row_uuid": { "col_uuid": true | false } }

{
  "results": {
    "Макароны": {
      "Плохо":  { "result": "1", "score": 2,    "is_correct": false },
      "Норм":   { "result": "",  "score": null,  "is_correct": false },
      "Хорошо": { "result": "",  "score": null,  "is_correct": true  }
    },
    "Картошка": {
      "Плохо":  { "result": "1", "score": 2,    "is_correct": true  },
      "Норм":   { "result": "",  "score": null,  "is_correct": true  },
      "Хорошо": { "result": "",  "score": null,  "is_correct": false }
    }
  },
  "answers": {
    "row-uuid-1": { "col-uuid-1": true, "col-uuid-2": false, "col-uuid-3": false },
    "row-uuid-2": { "col-uuid-1": true, "col-uuid-2": false, "col-uuid-3": false }
  },
  "is_bool": true
}

Полный пример payload

Реальный пример тела webhook-запроса со скорингом, несколькими типами вопросов и пользовательскими заголовками. UUID сокращены для читаемости.

{
  "headers": {
    "Authorization": "Bearer my-secret-token",
    "X-Source": "webask"
  },
  "extra_params": { "utm_source": "email", "utm_campaign": "spring2024" },
  "promo_code": null,
  "log_id": 1916713,
  "score_all": 52,
  "score_earned": 29,
  "score_percent": 55.8,
  "scores": {
    "user": 29,
    "max": 52,
    "by_question": {
      "uuid-choice-1":  0,
      "uuid-choice-2":  3,
      "uuid-rating-1":  0,
      "uuid-scale-1":   0,
      "uuid-matrix-1":  6
    }
  },

  "uuid-choice-1": {
    "title": "Выберите один вариант",
    "type": "choiceSingle",
    "question_uuid": "uuid-choice-1",
    "uuid": "uuid-choice-1",
    "results": [
      { "result": "Вариант Б", "score": 0, "is_correct": false }
    ],
    "score_count": 0,
    "score_max": 4,
    "is_correct_question": false,
    "other": "",
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-choice-2": {
    "title": "Отметьте подходящие варианты",
    "type": "choiceMultiple",
    "question_uuid": "uuid-choice-2",
    "uuid": "uuid-choice-2",
    "results": [
      { "result": "Вариант А", "score": 3, "is_correct": true }
    ],
    "score_count": 3,
    "score_max": 3,
    "is_correct_question": true,
    "other": "",
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-rating-1": {
    "title": "Оцените сервис",
    "type": "rating",
    "question_uuid": "uuid-rating-1",
    "uuid": "uuid-rating-1",
    "results": {
      "result": "4",
      "is_star": true,
      "score": 0,
      "score_num": false,
      "is_correct": false
    },
    "score_count": 0,
    "score_max": 2,
    "is_correct_question": false,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-scale-1": {
    "title": "По шкале от 1 до 10",
    "type": "scale",
    "question_uuid": "uuid-scale-1",
    "uuid": "uuid-scale-1",
    "results": {
      "result": "6",
      "score": 0,
      "is_correct": true
    },
    "score_count": 0,
    "score_max": 3,
    "is_correct_question": true,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-input-1": {
    "title": "Оставьте комментарий",
    "type": "input",
    "question_uuid": "uuid-input-1",
    "uuid": "uuid-input-1",
    "results": { "result": "Всё отлично!" },
    "score_count": null,
    "score_max": null,
    "is_correct_question": null,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-file-1": {
    "title": "Прикрепите файл",
    "type": "file",
    "question_uuid": "uuid-file-1",
    "uuid": "uuid-file-1",
    "results": [
      {
        "result": "https://app.webask.io/.../document.pdf",
        "file_ext": "pdf"
      }
    ],
    "score_count": null,
    "score_max": null,
    "is_correct_question": null,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  },

  "uuid-matrix-1": {
    "title": "Оцените блюда",
    "type": "matrix",
    "question_uuid": "uuid-matrix-1",
    "uuid": "uuid-matrix-1",
    "results": {
      "Макароны": {
        "Плохо":  { "result": "1", "score": 2,   "is_correct": false },
        "Хорошо": { "result": "",  "score": null, "is_correct": true  }
      },
      "Картошка": {
        "Плохо":  { "result": "1", "score": 2,   "is_correct": true  },
        "Хорошо": { "result": "",  "score": null, "is_correct": false }
      }
    },
    "answers": {
      "row-uuid-1": { "col-uuid-1": true, "col-uuid-2": false },
      "row-uuid-2": { "col-uuid-1": true, "col-uuid-2": false }
    },
    "is_bool": true,
    "score_count": 6,
    "score_max": 6,
    "is_correct_question": false,
    "inline_group_id": null,
    "inline_group_title": null,
    "is_inline_group_child": false
  }
}

Обратная совместимость

Поля скоринга (score_max, is_correct_question, is_correct внутри results) добавляются поверх базового формата. Старые поля не удаляются и не переименовываются.

Тестирование webhooks

Для тестирования webhooks можно использовать следующие инструменты:

webhook.site

Рекомендуемый сервис для тестирования webhooks

https://webhook.site

Перейдите на сайт, получите уникальный URL и используйте его для тестирования ваших webhooks.

Просмотр логов

Проверить работу webhook можно через логи

В интерфейсе WebAsk доступен просмотр логов отправки webhooks для отслеживания их работы.

Безопасность

Для обеспечения безопасности webhooks рекомендуется использовать HTTPS и проверять подлинность запросов.

Webhooks

Webhooks

Как подключить

Интерфейс настройки webhooks

Шаг 1: Переход в раздел интеграций

Шаг 2: Форма настройки webhook

Шаг 3: Тестирование webhook

Шаг 4: Просмотр логов

Настройки вебхука

Секретный токен через заголовок

Когда срабатывают webhooks

Событие: Ответ на опрос

Автоматическая отправка

Формат payload

Поля в корне payload

Поля объекта вопроса

Формат results по типу виджета

choiceSingle, choiceMultiple, yesno, dropdown

choiceMedia

ranking

rating

scale

slider

input, email, phone

datetime

file

matrix

Полный пример payload

Обратная совместимость

Тестирование webhooks

webhook.site

Просмотр логов

Безопасность

Рекомендации по безопасности

Формат `results` по типу виджета