Что такое Webhook Listener

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

Webhook Listener – это обработчик, который принимает HTTP-запросы с уведомлениями о событиях из внешней системы. Он проверяет запрос, извлекает данные и передает событие в дальнейшую обработку: например, для обновления CRM или запуска автоматического сценария.

Кто звонит в дверь интеграции

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

Webhook называют механизм уведомления, а listener – принимающую часть. Один только адрес ничего не выполняет: за ним должен работать обработчик с правилами проверки и дальнейших действий. В документации также встречаются названия «приемник вебхуков», «обработчик вебхука» или webhook endpoint.

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

Что происходит между запросом и задачей менеджеру

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

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

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

Надежный приемник умеет узнавать повтор

Уведомление может прийти повторно: например, отправитель не дождался ответа или оператор вручную повторил доставку. Конкретная политика зависит от сервиса, поэтому нельзя рассчитывать ни на обязательные повторы, ни на гарантированную однократность получения.

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

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

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

Адрес известен, но доверять рано

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

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

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

Что проверить до рабочего подключения

• Корректное событие приводит к ожидаемому действию
• Повтор одного уведомления не создает дубль результата
• Неверная подпись и неполные данные обрабатываются предсказуемо
• Сбой CRM не приводит к бесследной потере принятого события
• Запоздавшее уведомление не откатывает актуальный статус
• По идентификатору можно проследить путь от приема до результата

У webhook listener есть два доказательства исправности: отправитель получил предусмотренный ответ, а бизнес получил предусмотренный результат. Проверять нужно оба. Сам по себе зеленый код HTTP еще не делает интеграцию полезной, как штамп «входящее» не выполняет поручение.