Что такое Webhook

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

Webhook – это способ обмена данными, при котором одна система отправляет HTTP-уведомление другой системе после определенного события. Получатель заранее предоставляет адрес обработчика, а отправитель сообщает о событии без постоянных запросов с его стороны.

Сообщить о перемене вместо постоянной переклички

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

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

Такой механизм удобен, когда изменения происходят нерегулярно. Не нужно постоянно получать ответ «пока ничего». Но передача по событию не отменяет согласование правил. Сервис может поддерживать уведомления только об отдельных действиях, а сообщение – содержать лишь идентификатор объекта, по которому придется запросить подробности.

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

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

Адрес доставки обозначает точку входа. Код, который принимает запрос, называют Webhook Listener. Само уведомление – еще один участник этой схемы. В рабочем описании полезно различать все три понятия: куда отправить, что передать и как обработать.

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

Что согласовать между двумя системами

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

Формат JSON распространен, но не является обещанием любого вебхука. HTTP-метод, заголовки и структура тела определяются конкретной интеграцией. Слово «стандартный» в переписке не освобождает от чтения документации. Особенно если у каждой стороны собственная коллекция стандартов.

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

Путь оплаты от события до действия в CRM

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

В задаче интеграции Битрикс24 с внешними системами практический вопрос состоит в том, какое подтвержденное событие меняет запись CRM. Переход клиента на страницу «Спасибо» и уведомление от платежного сервиса – разные свидетельства. В проектировании обмена важно выбрать надежное основание и связать его с конкретной сделкой.

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

Почему повтор не должен становиться второй продажей

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

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

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