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

Вебхук простыми словами

API — это когда вы спрашиваете: «Есть ли новые оплаты?». Вебхук — когда сервис сам сообщает: «Пришла оплата, вот данные».

Технически вебхук — обычный HTTP-запрос (чаще всего POST с JSON), который внешняя система отправляет на заранее указанный вами URL в момент события. Вы не опрашиваете сервис, а ждёте уведомления.

Push и pull: в чём разница

На практике их комбинируют: вебхук сообщает о событии, а за подробностями вы идёте в API.

Где встречаются вебхуки

• Платёжные системы: платёж прошёл, отменён, возвращён. Магазин меняет статус заказа без участия менеджера.
• CRM: создана сделка, изменился этап воронки — данные уходят в мессенджер, склад или аналитику.
• Telegram-боты: в режиме webhook Telegram сам присылает каждое новое сообщение на ваш сервер.
• Git-хостинги: push в репозиторий запускает сборку и деплой.

Как правильно принимать вебхуки

1. Проверяйте подлинность

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

import crypto from "node:crypto";

function isValid(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Подпись считается по сырому телу запроса, а не по распарсенному JSON. Точный алгоритм и заголовок смотрите в документации провайдера.

2. Отвечайте быстро

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

3. Будьте готовы к повторам

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

4. Делайте обработку идемпотентной

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

• Заказ не должен оплачиваться дважды.
• Клиенту не должно уйти два одинаковых письма.
• Остаток на складе не должен списаться повторно.

5. Не доверяйте порядку

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

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

• Нет проверки подписи — любой может «подтвердить» оплату.
• Долгая обработка внутри запроса — провайдер считает доставку неудачной и шлёт повторы.
• Нет защиты от дублей — двойные списания и уведомления.
• Нет логов входящих событий — невозможно разобраться, что пошло не так.
• Endpoint без HTTPS.