Вебхук (Webhook): что это, для чего нужен и как настроить

Клиент оформил заказ на сайте, но заявка не появилась в CRM. Менеджеру приходится переносить контакты вручную или регулярно проверять новые обращения. Чтобы сервисы обменивались данными сами, можно настроить вебхук: сайт сообщит о заказе сразу после его оформления.

Но одной ссылки для такой интеграции недостаточно. Нужно определить событие, подготовить адрес получателя, согласовать формат запроса и убедиться, что система выполнила нужное действие. Есть и вопрос безопасности: по рекомендациям OWASP (проверено в 2026 году), входящие запросы следует проверять на подлинность.

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

Сотрудница интернет-магазина проверяет заявку на смартфоне и ищет данные клиента в CRM

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

Вебхук (webhook) — способ автоматически сообщать о событии через HTTP-запрос. Так сайт уведомляет CRM о заявке, а платежная система — об оплате. Получателю не нужно постоянно проверять обновления.

Вебхук — не просто ссылка: для работы нужны событие у отправителя, адрес доставки и обработчик у получателя. Без последнего запрос не запустит нужное действие.

Представим интернет-магазин, который передает заявки в CRM. Последовательность будет такой:

1. Покупатель заполняет форму и нажимает кнопку отправки.
2. Сайт сохраняет новую заявку и определяет, что произошло нужное событие.
3. Отправитель формирует HTTP-запрос и направляет его на адрес CRM.
4. Получатель читает сведения и создает карточку клиента либо ставит событие в очередь обработки.
5. Принимающий сервер возвращает HTTP-ответ о результате приема запроса.

У каждого запроса есть несколько важных частей. URL — адрес, куда его доставляют; он должен вести к обработчику, а не к произвольной странице. Метод определяет тип обращения. Для передачи вебхуков часто используют POST: он позволяет отправить сведения в теле запроса. Заголовки сообщают технические детали, например тип содержимого или данные для проверки подписи.

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

Получатель отвечает HTTP-статусом. Например, 200 OK подтверждает успешную обработку запроса на уровне HTTP, но карточка в CRM может появиться позже. Доставку и конечный результат проверяют отдельно.

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

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

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

Для интернет-магазина сочетание подходов часто удобнее одного способа. Вебхук сообщает CRM о новом заказе, а запрос к API позволяет уточнить его полный состав, получить актуальный статус или сверить сведения после сбоя. Если уведомление потерялось, такая сверка помогает обнаружить расхождение между системами.

Где используют вебхуки и когда они нужны

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

Событие	Куда поступают данные	Результат
Новая заявка	CRM	Создаётся карточка клиента и задача менеджеру
Успешная оплата	Система заказов	Заказ получает статус оплаты
Изменение заказа	Система уведомлений	Клиенту отправляют сообщение
Обновление кода	Система сборки	Запускается проверка проекта

Возьмем форму обратной связи на сайте. Покупатель оставляет имя, почту и вопрос. Сайт фиксирует обращение, отправляет уведомление, а CRM создает карточку, указывает источник заявки и назначает менеджера. При такой автоматизации CRM сотрудникам не нужно переносить каждый контакт из почты или таблицы.

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

Вебхук нужен не всегда

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

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

Что подготовить перед настройкой

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

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

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

Схема работы вебхука: от события на сайте до передачи данных в CRM и получения ответа сервера

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

Выберите точный тип события. Например, lead.created может означать новую заявку, а order.paid — оплату. Названия условные: реальные значения берут из документации. Не путайте создание заказа с его оплатой.

Сведения часто передают в формате JSON. Это набор полей с названиями и значениями. Для заявки могут потребоваться:

• event_id — идентификатор уведомления, который помогает узнать повторную доставку;
• lead_id — идентификатор самой заявки для поиска записи в CRM;
• created_at — дата и время события, обычно с указанием часового пояса;
• source — место, откуда пришло обращение: форма, магазин или другой канал;
• data — блок с содержимым заявки, например именем, почтой и вопросом клиента.

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

Где взять адрес для приема запросов

Webhook URL — адрес, на который отправитель направляет уведомления. Если CRM поддерживает входящие вебхуки, адрес обычно создают в разделе интеграций или автоматизации. Система выдает ссылку; ее целиком переносят в настройки отправителя. Иногда сначала нужно создать сценарий обработки, а уже потом получить адрес.

Второй вариант — собственный обработчик на сервере. Разработчик создает отдельный маршрут, например https://example.com/webhooks/leads, и настраивает программу, которая принимает HTTP-запросы по этому пути. Обычная страница сайта не подходит: адрес должен вести к действующему инструменту приема данных.

Получателю обычно нужен публичный HTTPS-адрес. На локальный localhost:3000 внешний сервис без дополнительной настройки не попадет. Для разработки используют тестовый сервер или защищенный туннель; перед запуском проверяют доступность адреса и сертификат.

Это важно

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

Разработчик настраивает передачу данных между сайтом и CRM на ноутбуке

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

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

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

Настройка без программирования

Если CRM не принимает входящие запросы напрямую, поможет инструмент автоматизации: он получит событие и создаст запись через интеграцию или API. Собственный сервер для этого не нужен.

1. Создайте прием события. Откройте CRM и найдите пункт «Интеграции», Webhooks, «Автоматизация» или похожий раздел. Выберите входящий вебхук либо сценарий, который начинается с HTTP-запроса. Укажите, какое действие система должна выполнить после получения заявки: создать клиента или обращение, сохранить контакты и назначить ответственного.
2. Скопируйте URL. После сохранения CRM или инструмент автоматизации выдаст адрес получателя. Перенесите его без изменений. Если адрес содержит секретный токен, не публикуйте его и не пересылайте посторонним: иногда сама ссылка служит ключом доступа.
3. Настройте отправителя. На сайте откройте настройки исходящих вебхуков или автоматических HTTP-запросов. Создайте правило, вставьте адрес получателя и выберите событие «Новая заявка» или его аналог. Проверьте, что речь идет именно об отправке формы, а не о просмотре страницы или изменении черновика.
4. Согласуйте параметры. Если платформа позволяет выбирать метод, для такого сценария обычно указывают POST. При передаче JSON в заголовке Content-Type используют значение application/json. Уточните, нужны ли дополнительные заголовки, токен или подпись. Если сервис заполняет параметры автоматически, следуйте его документации, а не меняйте значения наугад.
5. Сопоставьте поля. Проверьте, куда попадут имя, телефон, электронная почта и комментарий. Например, значение email из формы должно оказаться в поле электронной почты клиента, а не в заметках. Укажите обязательные поля и определите, что делать, если посетитель оставил часть формы пустой.
6. Сохраните и проверьте. Отправьте заявку с тестовыми контактами. Откройте CRM, найдите новую карточку и убедитесь, что система сохранила сведения и запустила предусмотренное действие. Если подключение не сработало, посмотрите статус отправки и проверьте URL, выбранное событие и соответствие полей.

Создание обработчика на сервере

Свой обработчик полезен для сложной логики. Например, заявки из разных форм можно направлять в разные отделы CRM после проверки их источника. Понадобятся разработчик и доступный через интернет сервер.

Обработчик пишут, например, на Python или JavaScript. При создании Telegram-бота на Python тот же подход позволяет получать сообщения через вебхук вместо регулярного опроса.

Работу разработчика удобно разбить на пять этапов:

1. Создать адрес приема. На сервере настраивают отдельный HTTPS-маршрут, например https://example.com/webhooks/leads. Адрес должен принимать запросы нужным методом и быть доступным снаружи. Само наличие сайта на домене еще не означает, что маршрут работает.
2. Принять и разобрать запрос. Программа читает заголовки и тело сообщения, определяет тип события, проверяет обязательные поля. Сначала необходимо проверить подлинность запроса по правилам отправителя, а затем разбирать его содержимое и запускать действия.
3. Надежно сохранить событие. После проверки обработчик записывает уведомление в базу данных или очередь задач. Нужно сохранить идентификатор события, чтобы отличать новые запросы от повторных и иметь возможность восстановить обработку после сбоя.
4. Выполнить нужное действие. Программа передает контакты в CRM и запускает создание карточки. Если процесс долгий, его можно вынести в отдельную задачу, чтобы сервер не удерживал соединение до завершения всей работы.
5. Вернуть ответ. Сервер подтверждает успешный прием подходящим HTTP-статусом, обычно из диапазона 2xx. Важно отправлять такое подтверждение после надежного сохранения события. Если прием не удался, ответ должен отражать ошибку, иначе отправитель может посчитать уведомление доставленным.

Представим, что сайт отправил событие с условным названием lead.created. В уведомлении есть event_id — идентификатор события, lead_id — номер заявки, created_at — время ее появления, а также data с почтой test@example.com. Это не обязательный стандарт: другой сервис может использовать иные названия или вовсе не присылать часть полей.

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

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

После подключения проверьте два результата: доставку HTTP-запроса и действие принимающей системы. Это разные этапы. Например, сайт получил ответ 200 OK, но CRM не создала карточку, потому что в уведомлении отсутствовала электронная почта. Код из диапазона 2xx сообщает об успешной обработке запроса на уровне HTTP. Он не всегда подтверждает, что последующие действия завершились.

Проверка тестовым событием

Создайте заявку в форме сайта с вымышленным именем и контактами. Зафиксируйте, какие значения указали, и отправьте форму один раз. Затем откройте раздел вебхуков на сайте. Журнал может называться «История доставки», «События», «Запросы» или Logs. В нем найдите отправку, соответствующую времени теста.
Проверьте следующие сведения:

• URL получателя. Сверьте адрес с настройками интеграции, включая путь.
• Время и идентификатор события. Помогают найти отправку и отличить ее от повтора.
• HTTP-статус. Показывает результат приема. При отсутствии ответа ищите сетевую ошибку или таймаут.
• Тело и заголовки. Сверьте тип события, формат и поля. Не копируйте секреты в открытые отчеты.

В серверной горит индикатор ошибки на оборудовании, которое принимает запросы вебхука

В CRM найдите запись с тем же номером заявки. Проверьте контакты и назначение менеджера. Если записи нет, ищите ошибку в сценарии автоматизации, а не только в доставке.

Сверьте поля: отправитель может передавать номер в lead_id, а CRM искать id. Ошибка возникнет и тогда, когда вместо числа приходит текст или обязательное поле email пустует.

Для диагностики можно временно использовать тестовый адрес, который показывает заголовки и тело запроса. Не отправляйте туда реальные контакты и секреты. После теста верните рабочий URL и проверьте действие в CRM.

Почему вебхук не работает

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

Если попытка отправки есть, но получатель сообщил об ошибке, ориентируйтесь на код ответа:

• 400 Bad Request — запрос не прошел проверку. Возможны неверный формат JSON, пустое обязательное поле или некорректная структура.
• 401 Unauthorized или 403 Forbidden — получатель отказал в доступе. Проверьте ключи, подпись, токен и права учетной записи.
• 404 Not Found — сервер не нашел указанный маршрут. Сравните URL с адресом, который выдал получатель.
• 405 Method Not Allowed — адрес есть, но метод запроса не подходит. Например, получатель принимает POST, а отправитель посылает GET.
• 429 Too Many Requests — превышен допустимый темп запросов. Уточните лимиты и правила повторных попыток.
• 500 Internal Server Error или 503 Service Unavailable — на стороне получателя произошел сбой или сервис временно недоступен. Проверьте его состояние и журналы

Если ответа нет, проверьте соединение, доступность сервера и сертификат HTTPS. При таймауте выясните, успел ли получатель сохранить событие: повторная попытка может привести к дублю.

Если запрос дошел, но действия нет, помогут мониторинг и логирование сервера. В готовой CRM смотрите журнал сценариев автоматизации.

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

Чек-лист готовности вебхука:

• Нужное событие запускает отправку на правильный адрес.
• Получатель принимает запрос и возвращает ожидаемый HTTP-ответ.
• Обязательные поля сохраняют правильные названия, типы и значения.
• CRM выполняет конечное действие: создает карточку, задачу или обновляет статус.
• Неверный либо неподписанный запрос не приводит к ошибочному бизнес-действию.
• Ошибки доставки и обработки можно найти в журналах.
• Повтор того же события не создает второй заказ или другую лишнюю операцию.

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

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

Проверка подлинности запросов

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

Для проверки подлинности сервисы используют секретные токены или криптографическую подпись. Распространенный вариант — HMAC. Отправитель с помощью секретного ключа создает подпись сообщения и передает ее вместе с запросом. Получатель рассчитывает свою подпись с тем же ключом. Если проверка прошла, это подтверждает, что данные соответствуют сообщению от стороны, которая знает секрет.

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

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

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

Защита от повторной обработки

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

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

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

Обработчику не всегда нужно ждать окончания всей работы. После проверки подлинности и структуры он может надежно сохранить событие в базе или очереди, вернуть успешный HTTP-ответ и создать карточку отдельной задачей. Это асинхронная обработка: она уменьшает риск таймаута при долгой операции. Но отвечать 200 OK до сохранения события опасно. Если сервер потеряет данные после ответа, отправитель может не прислать их еще раз.

Запомните

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

Менеджер интернет-магазина передает клиенту заказ после обработки заявки в CRM

Заключение

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

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

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

Вам нужна биржа фриланса для новичков или требуются разработчики сайтов?