Изменение объекта
Новая сделка, смена статуса, готовый документ, оплата или другое поддерживаемое событие запускает обработку.
Webhooks: системы сообщают о событии сами
Используем webhooks, когда система может сама сообщить о создании, изменении или результате операции. Это позволяет не опрашивать API без необходимости, но требует отдельной логики проверки источника, повторных событий, порядка обработки и связи события с конкретным объектом бизнеса.
Событие → обработчик → результат
Событиевнешняя система сообщает об изменении
→Webhook endpointпроверка источника и формата
→Обработчикидемпотентность и бизнес-логика
→Результатизменение или статус в системе
→Когда использовать
Webhook подходит для события, а не заменяет полноценную синхронизацию
Если нужно узнать о конкретном изменении сразу после него, webhook обычно удобнее постоянного опроса. Для сверки больших наборов данных и восстановления состояния может дополнительно потребоваться обычный API.
Результат операции
Внешний сервис сообщает, что ранее созданная операция завершилась или перешла в новое состояние.
Связь систем
Полученное событие сопоставляется с конкретной сделкой, заказом, документом или другим объектом.
Мгновенная реакция
После подтверждённого события можно поставить задачу, изменить поле, отправить уведомление или запустить следующий этап.
Обработка
HTTP-запрос и бизнес-операция — не одно и то же
Endpoint должен быстро проверить и принять событие, а тяжёлую обработку при необходимости можно вынести в очередь.
Webhook пришёл→Проверка источника→Проверка event ID→Быстрый ответ→Очередь / обработка→Бизнес-результат
Контракт события
До разработки фиксируем, что именно считается уникальным событием и как найти связанный объект
Без этого повторная доставка или изменение порядка событий превращается в дубли и неверные статусы.
Идентификатор события
Если поставщик передаёт стабильный event ID, используем его для контроля повторной обработки.
Идентификатор объекта
Заказ, сделка, документ или внешний номер должны сопоставляться однозначно.
Тип события
Разные состояния обрабатываем отдельными правилами, а неизвестные типы не трактуем как успешный результат.
Версия и время
Когда порядок событий важен, учитываем доступные признаки версии или времени и не перезаписываем новое состояние старым без проверки.
Исходные данные
Храним достаточный журнал входящего события и результата обработки для диагностики, не дублируя лишние персональные данные.
Безопасность
Публичный webhook endpoint нельзя считать доверенным только потому, что URL никому не показывали
Способ проверки зависит от поставщика: подпись, секрет, токен, allowlist или другая поддерживаемая схема. Если сервис не даёт криптографической подписи, компенсируем это ограничениями сценария и дополнительными проверками.
Проверка источника
Используем механизм аутентификации или подписи, который реально поддерживает отправитель.
Минимальные права
Webhook не получает больше возможностей, чем требуется конкретному сценарию.
Идемпотентность
Повтор одного события не создаёт второй документ, заказ или исходящее сообщение.
Журнал ошибок
Отделяем временную ошибку внешней системы от некорректного события и сохраняем понятную причину.
Очереди и повторы
Повтор HTTP-запроса поставщиком и наш повтор бизнес-операции требуют разных правил
Получатель может получить одно событие несколько раз, а внешний API может временно не отвечать. Эти ситуации обрабатываются независимо.
Принимаем событие
Проверяем формат и источник.
Проверяем повтор
Смотрим уникальный ключ и ранее сохранённый результат.
Фиксируем задание
Для важной операции сохраняем её до внешнего вызова.
Выполняем действие
С контролируемым timeout и правилами безопасного повтора.
Сохраняем итог
Статус виден сотруднику и доступен для повторной сверки.
Webhook + API
Лучший сценарий часто использует webhook для сигнала, а API — для получения актуального состояния
Не требуем от события содержать весь объект, если после него можно запросить нужные данные по стабильному идентификатору.
Архитектура
Событие говорит «что-то изменилось», API подтверждает нужные данные
Так интеграция меньше зависит от состава payload конкретного webhook и проще восстанавливается после пропущенного или повторного события.
Вопросы
Частые вопросы
Webhook и API — это одно и то же?
Нет. Webhook обычно доставляет событие от системы к нашему endpoint, а API используется, когда наш сервис сам запрашивает данные или выполняет операцию. В одном процессе часто используются оба механизма.
Почему одно событие может прийти несколько раз?
Многие системы повторяют доставку, если не получили ожидаемый ответ или не уверены в результате. Поэтому обработчик должен безопасно распознавать уже обработанное событие.
Нужно ли отвечать webhook только после завершения всей логики?
Не всегда. Для тяжёлых операций надёжнее быстро принять проверенное событие, сохранить задание и продолжить обработку отдельно, если контракт поставщика это допускает.
Как проверить, что webhook пришёл от нужного сервиса?
Используем поддерживаемую отправителем схему: подпись запроса, секрет, токен, ограничения источника или их комбинацию. Универсального метода для всех сервисов нет.
Что делать, если события пришли не по порядку?
Если порядок влияет на бизнес-статус, используем доступные версии, время, текущий статус объекта и дополнительные запросы к API, чтобы старое событие не откатило новое состояние.
Можно полностью отказаться от cron после внедрения webhooks?
Только если поставщик гарантирует все необходимые события и процесс не требует периодической сверки. Для критичных интеграций иногда оставляем редкий контроль состояния как отдельный механизм восстановления.
Какое событие сейчас приходится проверять вручную?
Покажите источник, пример события и нужное действие после него. Определим контракт webhook, защиту от повторов и способ восстановления при ошибке.