Вебхук CRM: как описать событие и защититься от повторной обработки

Назовите событие предметно

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

Вебхук должен сообщать о понятном изменении: принято обращение, изменён статус или готов результат. Получателю нужен стабильный идентификатор, тип и достаточный контекст. Не пересылайте всю базу ради одного изменения. До реализации договоритесь о смысле сообщения и версии формата. Тогда техническая команда сможет отличить новую потребность от обновления прежней записи, а повтор одной отправки — от отдельного самостоятельного действия пользователя.

Согласуйте повторную доставку

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

Сеть может оборваться после того, как получатель уже применил событие, но до подтверждения отправителю. Повтор в такой ситуации нормален, если обработка защищена от лишних последствий. Опишите, как идентификатор используется для распознавания уже принятого сообщения. Не полагайтесь на совпадение времени или имени клиента. Иначе два настоящих обращения могут ошибочно объединиться, а один технический повтор — создать несколько продаж с одинаковым содержанием.

Определите подтверждение приёма

Здесь важно учесть риск: наличие веб-интерфейса CRM не означает наличие публичных вебхуков или документированного интеграционного контракта.

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

Проверьте доступ и ограничения

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

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

Проверьте отказ и восстановление

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

Частые вопросы