Webhook

Что это значит

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

От API он отличается направлением. API мы спрашиваем сами, когда что-то нужно; вебхук приходит сам, без повторяющихся запросов со стороны системы.

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

Как это работает на практике

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

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

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

На что обратить внимание

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

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