Webhook простыми словами: как система узнаёт, что что-то произошло

Webhook — это способ сообщить другой системе: «что-то произошло, пора действовать». В отличие от обычного запроса, где одна система постоянно спрашивает «есть новое?», webhook работает как уведомление — сигнал приходит в момент события.

Общая картина

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

sequenceDiagram
    participant A as Сервис-источник
    participant B as Ваш backend
    Note over A,B: Регистрация webhook URL
    A->>B: POST /webhook (событие: оплата прошла)
    B->>B: Проверка подписи
    B->>B: Обработка данных
    B-->>A: 200 OK

Аналогия без технологий: вы не звоните курьеру каждые пять минут с вопросом «приехал?». Курьер сам пишет, когда подъехал. Webhook устроен так же.

Webhook vs API-запрос

Типовые примеры

• Оплата: клиент оплатил заказ → платёжный сервис (YooKassa, Stripe, Тинькофф) отправляет webhook на backend → backend обновляет статус заказа и отправляет чек.
• Форма: человек заполнил форму на сайте → сайт отправляет событие → CRM создаёт лид и отправляет уведомление менеджеру.
• Notion: в базе данных появилась новая страница → webhook уходит на backend → агент запускает обработку.
• Telegram: пользователь написал боту → Telegram отправляет webhook → бот обрабатывает сообщение и отвечает.
• GitHub: в репозиторий пришёл новый commit → GitHub отправляет webhook → CI/CD запускает сборку и тесты.

Как устроен webhook технически

Webhook — это обычный HTTP POST-запрос с данными в формате JSON. Типичная структура:

1. URL получателя — адрес, куда сервис отправит запрос. Вы регистрируете его заранее в настройках сервиса.
2. Заголовки (headers) — содержат подпись запроса для проверки подлинности.
3. Тело запроса (body) — JSON с данными события: тип события, идентификаторы, метаданные.

{
  "event": "payment.succeeded",
  "payment_id": "pay_abc123",
  "amount": 5000,
  "currency": "RUB",
  "timestamp": "2026-05-11T12:00:00Z"
}

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

Идемпотентность

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

Проверка подписи

Большинство сервисов подписывают webhook-запросы секретным ключом. Backend должен проверять подпись перед обработкой — иначе злоумышленник может подделать запрос.

Таймауты

Сервис-отправитель ждёт ответ ограниченное время (обычно 5–30 секунд). Если обработка долгая — принимайте webhook быстро (ответ 200 OK), а обработку ставьте в очередь.

Логирование

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

Webhook и очереди

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

1. Принять webhook → ответить 200 OK.
2. Положить данные в очередь (Redis, RabbitMQ, BullMQ).
3. Фоновый воркер достаёт задачу и обрабатывает.

Так webhook не блокируется, обработка не теряется при ошибке, а повторные попытки работают корректно.

Чеклист: безопасная работа с webhook

По теме

• Статья: Как я собрал команду из трёх ИИ-агентов и автоматизировал разработку через Notion
• Блог: n8n встроил MCP-сервер — и теперь ваши ИИ-агенты сами собирают автоматизации
• База знаний: MCP (Model Context Protocol) — стандарт подключения ИИ к внешним системам

Если вы настраиваете webhook-интеграции и хотите разобраться, как связать события с агентами и автоматизацией — пишите в Telegram @pimenov.