Get in touch
Back to archive
13.09Server-side и API-интеграции

Webhooks: мгновенные события между системами

intermediate3 min readwebhooks · api · automation

TL;DR

  • Webhook - это способ, при котором одна система сама отправляет уведомление другой системе, когда произошло событие.
  • В отличие от polling, вам не нужно постоянно спрашивать CRM: "что-то изменилось?" CRM сама сообщает об изменении.
  • Webhooks хороши для быстрых маркетинговых пайплайнов: новый лид, смена статуса, оплата, отмена, возврат.
  • Надежный webhook endpoint должен проверять подпись/секрет, отвечать быстро, писать логи, делать retry и защищаться от дублей.
  • Webhook без очереди и idempotency часто работает нормально в демо, но ломается в продакшене.

1. Что такое webhook

API request - это когда вы сами идете в систему и спрашиваете данные. Webhook - это когда система сама стучится к вам.

Пример:

  • в amoCRM создана новая сделка;
  • amoCRM отправляет POST-запрос на ваш URL;
  • ваш endpoint принимает событие;
  • дальше вы отправляете quality event в рекламную систему или кладете данные в DWH.

Webhook - это не магия. Это обычный HTTP-запрос, просто инициатором является внешняя система.

2. Polling vs webhook

ПодходКак работаетКогда использовать
PollingВаш сервис регулярно спрашивает APIСверки, nightly jobs, восстановление
WebhookВнешняя система сама отправляет событиеБыстрые реакции, статусы, уведомления

Polling проще контролировать, но он медленный и может грузить API. Webhooks быстрее, но требуют надежного приема.

Хорошая архитектура часто использует оба подхода: webhooks для real-time событий, polling для ежедневной сверки и восстановления пропусков.

3. Что должен делать webhook endpoint

Минимальный endpoint:

  1. Принять запрос.
  2. Проверить секрет или подпись.
  3. Проверить формат.
  4. Вернуть 200 OK быстро.
  5. Положить событие в очередь.
  6. Обработать событие отдельно.
  7. Записать лог.

Не надо в рамках одного HTTP-запроса делать все: обращаться в CRM, Meta, Google, TikTok, BigQuery и Slack. Если один внешний API тормозит, webhook sender может решить, что ваш endpoint упал.

4. Idempotency и дубли

Внешняя система может отправить webhook повторно. Это нормально. Повтор может случиться из-за таймаута, сетевой ошибки или retry-политики.

Поэтому обработчик должен быть idempotent: повторная обработка того же события не должна создавать дубль.

Практический ключ:

  • event_id;
  • webhook_id;
  • lead_id + status + timestamp;
  • order_id + event_name.

Если событие уже обработано, worker должен пропустить его или обновить запись, а не отправить вторую конверсию в рекламный кабинет.

5. Где webhooks нужны маркетингу

Типичные use cases:

  • новая заявка в CRM;
  • смена статуса сделки;
  • успешная оплата;
  • возврат или отмена;
  • подписка продлена;
  • пользователь прошел onboarding;
  • менеджер назначил встречу;
  • call tracking пометил звонок как качественный;
  • форма получила spam score.

Для marketing ops webhooks - это клей между системами. Они позволяют не ждать ручных выгрузок и не жить в Excel.

6. Локальный контекст СНГ/РК

В локальных проектах webhooks часто делают через Make, Albato, Zapier, n8n или самописный endpoint. Это нормально для старта, но важно понимать границы.

No-code-инструмент удобен, когда:

  • объем небольшой;
  • данные не слишком чувствительные;
  • нужна быстрая проверка гипотезы;
  • команда не готова писать backend.

Самописный слой нужен, когда:

  • много событий;
  • есть PII;
  • нужны retries и очереди;
  • есть SLA;
  • нужно контролировать логи;
  • ошибки стоят денег.

7. Ошибки

ОшибкаПоследствие
Endpoint делает тяжелую обработкуTimeout и повторы
Нет проверки подписиЛюбой может отправить фейковое событие
Нет idempotencyДубли лидов и конверсий
Нет логов raw payloadНевозможно расследовать ошибку
Нет retryСобытия теряются
Нет dead-letter queueНеясно, что не обработалось

8. Чеклист

  • У webhook URL есть секрет или подпись.
  • Endpoint отвечает быстро.
  • События кладутся в очередь.
  • Есть idempotency key.
  • Есть retry policy.
  • Есть dead-letter storage для ошибок.
  • Логи не содержат лишних PII.
  • Есть ежедневная сверка с источником.

9. Видео

Что такое Webhook и чем отличается от API?

10. Главный совет

Webhook должен быть скучным и надежным. Если он выглядит как красивый no-code сценарий без логов, retry и защиты от дублей, он еще не готов кормить рекламные алгоритмы.

Sources / Notes