Вебхук (Webhook)

Вебхук это способ доставки данных, при котором сервис сам отправляет вам HTTP-запрос, когда произошло событие. В опросах событие обычно одно и понятное: человек дошёл до конца анкеты.

Что такое вебхук

Обычный порядок работы с чужим сервисом такой: вы обращаетесь к его API и спрашиваете, не появилось ли чего нового. Вебхук переворачивает инициативу. Вы один раз даёте сервису адрес, а он стучится к вам сам, как только есть о чём сообщить.

Разница не в возможностях, а в цене и задержке. Если опрашивать API раз в пять минут, то в среднем данные приходят с задержкой в две с половиной минуты, а почти все запросы возвращают пустоту. Вебхук отдаёт данные сразу и лишних запросов не делает, но требует от вас публичного адреса и работающего обработчика.

Из чего состоит вызов

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

POST /webask-hook HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "survey_id": 12345,
  "response_id": "a1b2c3",
  "completed_at": "2026-09-03T10:15:00Z",
  "answers": { "q1": 9, "q2": "быстрая доставка" }
}

Тело обычно приходит в JSON. Из него для практики важнее всего идентификатор ответа: именно он позволяет отличить повторную доставку от нового заполнения, о чём ниже.

Когда вебхук вообще нужен

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

Способ	Что требует	Когда подходит
Готовая интеграция	ничего, включается в опросе	Telegram, Битрикс24 и другие типовые адресаты
Zapier	аккаунт и настройка сценария	таблицы, почта, сотни сервисов без кода
Вебхук	свой адрес и обработчик	своя система, нестандартная логика
Запросы к API	свой код и расписание	когда нужна вся история, а не одни свежие ответы

Из таблицы видно правило выбора. Если адресат типовой, берите готовую интеграцию или Zapier: вебхук в этом случае просто добавит вам работы. Вебхук выигрывает, когда данные должны попасть в вашу собственную систему, и особенно когда в момент ответа надо что-то сделать: создать заявку, разбудить дежурного, поставить задачу.

Главная практическая проблема: дубли

Про это не пишут в кратких руководствах. А спотыкаются об это все.

Доставка вебхуков почти всегда устроена по принципу «хотя бы один раз». Отправитель обязан убедиться, что запрос дошёл, и признаком успеха служит ваш ответ с кодом 200. Если ваш обработчик думал слишком долго и ответ не успел вернуться, отправитель считает попытку неудачной и повторяет её. Событие было одно, а записей у вас теперь две.

Из той же природы доставки следует второе правило: порядок не гарантирован. Два ответа, заполненных подряд, могут прийти в обратном порядке. Если логика зависит от очерёдности, опирайтесь на время из тела запроса, а не на время получения.

Вебхук это не архив

Отсюда важное следствие. Если ваш обработчик лежал, отправитель какое-то время будет повторять попытки, а потом перестанет. Сколько именно попыток и с какими интервалами, смотрите в документации конкретного сервиса, а факт повторов видно в логах интеграции.

Значит на вебхук нельзя опираться как на единственный источник данных. Он хорош, чтобы реагировать в момент события, и плох, чтобы хранить. Полноту данных обеспечивают выгрузка и запросы к API: там всегда лежит вся история, независимо от того, дошёл ли конкретный вызов. Разумная схема такая: вебхук запускает действие сразу, а сверка с выгрузкой раз в сутки ловит пропущенное.

Что можно передать вместе с ответом

Часто нужно, чтобы вместе с ответами пришёл контекст: из какого канала человек пришёл, на каком этапе воронки находится, какой у него тариф. Для этого в ссылку на опрос добавляются скрытые переменные, и их значения приходят рядом с ответами.

Это заметно упрощает жизнь получателю: не нужно сопоставлять ответ с человеком по почте или по времени, идентификатор из вашей системы приходит сразу в теле запроса.

Безопасность: что важно на самом деле

Общие советы про обновления и мониторинг относятся к вебхукам не больше, чем к любому другому коду. Специфических вещей всего четыре.

• адрес держите на HTTPS: тело уходит открытым текстом, а в нём ответы людей
• проверяйте, что запрос от вашего сервиса: адрес обработчика не секрет, и постучаться на него может кто угодно
• не доверяйте телу запроса: это внешние данные, их надо проверять перед записью в базу, как любую форму на сайте
• ограничьте частоту: обработчик, который открыт всем, легко завалить потоком запросов
• не кладите в адрес вебхука ничего чувствительного: он попадает в логи и на стороне отправителя, и у вас

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

Вебхук в WebAsk

Вебхук здесь привязан к конкретному опросу и срабатывает на завершённое прохождение. Подключается он в разделе интеграций.

1. Откройте нужный опрос и перейдите в интеграции, в блок вебхуков.
2. Задайте название, адрес получателя и тип запроса.
3. При необходимости укажите имя и значение дополнительного поля и выберите, какие элементы анкеты отправлять.
4. Проверьте доставку до подключения к своей системе.

Последний шаг стоит делать всегда, и для него не нужен свой сервер: подставьте адрес с сервиса вроде webhook.site, пройдите опрос сами и посмотрите, что именно пришло. Так вы заодно увидите, куда попадает то дополнительное поле, и сможете использовать его как общий секрет. Отправленные вызовы видны в логах интеграции, там же ищите причину, если данные не дошли.

Если своего обработчика нет и писать его некому, вебхук вам не нужен: посмотрите на Zapier, готовые интеграции с Telegram и Битрикс24 или на API. Подробная инструкция по вебхукам лежит в базе знаний.

Частые ошибки

Долгая обработка внутри запроса. Обработчик, который сам звонит в три сервиса и потом отвечает, получает таймауты и повторы. Принимайте, отвечайте, обрабатывайте потом.

Ответ не 200. Любой другой код отправитель читает как неудачу и повторит запрос. Если данные вам не нужны, всё равно отвечайте успехом, а фильтруйте у себя.

Локальный адрес. Адрес вида localhost или внутренний адрес сети недостижим со стороны сервиса. Для отладки нужен либо публичный адрес, либо тестовый приёмник.

Расчёт на порядок и на единственность. Два самых частых источника расхождений в данных. Оба лечатся идентификатором ответа и временем из тела запроса.

API Экспорт данных (Data Export)

Коротко

• Вебхук это доставка по инициативе сервиса, в отличие от запросов к API по вашей инициативе.
• В WebAsk он привязан к опросу и срабатывает на завершённое прохождение.
• Если адресат типовой, готовая интеграция или Zapier обойдутся дешевле вебхука.
• Одно событие может прийти дважды: отвечайте 200 сразу и отбрасывайте повторы по идентификатору.
• Порядок доставки не гарантирован, ориентируйтесь на время из тела запроса.
• Из безопасности важны HTTPS, проверка отправителя общим секретом и недоверие к телу запроса.

Вопросы и ответы

Чем вебхук отличается от API?

Направлением инициативы. К API вы обращаетесь сами и спрашиваете, есть ли новое, а вебхук сервис отправляет вам сам в момент события. Поэтому вебхук быстрее и дешевле по запросам, но требует публичного адреса и обработчика на вашей стороне.

Почему один ответ пришёл дважды?

Потому что отправитель не получил от вас подтверждения вовремя и повторил попытку. Это нормальное поведение, а не сбой. Отвечайте кодом 200 сразу после приёма и отбрасывайте запросы с уже знакомым идентификатором ответа.

Нужен ли вебхук, если я просто хочу ответы в таблице?

Нет. Для типовых адресатов вроде таблиц, почты или мессенджеров есть готовые интеграции и Zapier, там не нужен код. Вебхук нужен, когда данные должны попасть в вашу собственную систему или в момент ответа надо что-то запустить.

Как проверить вебхук, если своего сервера нет?

Подставьте адрес тестового приёмника, например с сервиса webhook.site, пройдите опрос самостоятельно и посмотрите пришедший запрос. Так видно и структуру тела, и то, какие элементы анкеты отправляются.

Как защитить обработчик от посторонних запросов?

Договоритесь об общем секрете и передавайте его в заголовке, а получатель пусть отвергает запросы без него. В адрес секрет класть не стоит: адреса попадают в логи на обеих сторонах.