Команда разработки уведомлений сталкивается с классической проблемой: она должна отправить данные о завершении оплаты в систему CRM, но не знает, когда именно CRM получит эти данные и как понять, что обработка прошла успешно. Без чёткого контракта каждая сторона придумывает свой формат, а отладка занимает дни. Webhook — это механизм push-уведомления, где источник событий инициирует HTTP-запрос к подписчику. Чтобы этот обмен был предсказуемым, необходимо формализовать три аспекта: структуру самого события (payload), правила доставки (retry, timeout) и протокол подтверждения (acknowledgement). В этой статье мы разберём, как описать каждый из этих элементов, используя конкретный учебный пример интеграции платёжного сервиса с CRM.
Анатомия webhook-события
Webhook-событие — это HTTP POST-запрос, тело которого содержит данные о произошедшем изменении. Критически важно разделить метаинформацию о событии от полезных данных. Метаинформация включает уникальный идентификатор события (event_id), тип события (type) и временную метку (timestamp). Полезные данные (data) зависят от типа события. Например, для события payment.completed поле data будет содержать ID платежа, сумму, статус и ссылку на детальный ресурс. Такой подход позволяет потребителю фильтровать события по типу, обрабатывая только те, которые ему интересны, и использовать event_id для обеспечения идемпотентности обработки.
Контракт структуры Payload
Структуру payload можно описать JSON Schema или схемой соответствующего OpenAPI. В OpenAPI 3.0 nullable: true при явно заданном type добавляет допустимость null, а наличие поля отдельно регулирует required. Необязательное поле не становится nullable автоматически. В 3.1 используются правила выбранного диалекта JSON Schema. Эти различия подтверждаются OpenAPI 3.0.3 и проверяются на конкретных примерах.
/components/schemas/PaymentCompletedEvent:
type: object
required:
- event_id
- type
- timestamp
- data
properties:
event_id:
type: string
description: Уникальный идентификатор события (UUID)
type:
type: string
enum: ["payment.completed"]
timestamp:
type: string
format: date-time
data:
type: object
required:
- payment_id
- amount
- currency
- status
properties:
payment_id:
type: string
amount:
type: number
format: decimal
currency:
type: string
length: 3
status:
type: string
enum: ["succeeded", "failed"]
Этот контракт служит основой для генерации тестов и валидации на стороне отправителя. Отправитель обязан гарантировать, что каждый исходящий запрос соответствует этой схеме. Потребитель, в свою очередь, использует её для входной валидации, отклоняя несоответствующие данные с ошибкой 400 Bad Request.
Правила доставки и Retry-политика
Сети ненадёжны, поэтому доставка webhook-событий не может гарантировать успех с первой попытки. Стандартная практика — реализовать exponential backoff (экспоненциальное увеличение интервала повторов). Если первый запрос завершается ошибкой (таймаут, 5xx статус), отправитель повторяет попытку через определённое время. Интервал увеличивается с каждой неудачной попыткой. Например: первая попытка сразу, вторая через 1 минуту, третья через 5 минут, четвёртая через 30 минут. Максимальное количество попыток ограничено, например, пятью. После исчерпания лимита событие считается недоставленным и логируется для ручного вмешательства. Важно отличать ошибки клиента (4xx) от ошибок сервера (5xx). На 4xx (кроме 429 Too Many Requests) повторять доставку бессмысленно, так как проблема в самом payload или URL, а не во временном сбое сети. Повторы применяются только к сетевым ошибкам и кодам 5xx/429.
Протокол подтверждения (Acknowledgement)
Как отправитель узнаёт, что событие обработано? Ответом является HTTP-статус-код. По соглашению, потребитель должен вернуть 2xx (обычно 200 OK или 202 Accepted) для успешной обработки. Код 202 особенно уместен, если обработка асинхронная: потребитель принял событие в очередь, но ещё не закончил работу. Если потребитель возвращает любой другой код (4xx, 5xx) или не отвечает вовсе (timeout), отправитель считает доставку неуспешной и запускает retry-логику. Некоторые сложные схемы используют явный callback URL или separate ACK endpoint, но для большинства случаев достаточно статуса ответа на исходный POST-запрос. Ключевой момент: подтверждение должно происходить быстро. Если обработка занимает много времени, потребитель должен сначала ответить 202, а затем выполнять тяжёлую работу в фоне. Иначе таймаут отправителя прервёт соединение, хотя логически событие могло быть принято.
Идемпотентность обработки
Из-за retry-логики одно и то же событие может быть доставлено несколько раз. Потребитель обязан быть идемпотентным: повторная обработка одного и того же event_id не должна приводить к побочным эффектам (например, двойному начислению бонуса). Реализация обычно сводится к хранению списка обработанных event_id в кэше или базе данных с TTL (Time To Live), равным максимальному периоду retry. Если event_id уже найден, потребитель просто возвращает 200 OK, игнорируя тело запроса. Это защищает от дубликатов, вызванных сетевыми сбоями или длительной работой обработчика, превышающей таймаут отправителя.
Sequence-диаграмма взаимодействия
Визуализация процесса помогает выявить узкие места. Ниже представлена диаграмма PlantUML, описывающая сценарий успешной доставки с одним повтором. Она показывает взаимодействие трёх участников: Payment Service (отправитель), Network (канал передачи) и CRM System (приёмник). Диаграмма иллюстрирует, как таймаут первого запроса приводит к повтору, и как приёмник использует event_id для фильтрации дублей.
@startuml
actor User
participant "Payment\nService" as PS
participant "Network" as Net
participant "CRM\nSystem" as CRM
User -> PS: Create Payment
PS -> PS: Process & Commit
PS -> Net: POST /webhooks\nevent_id=abc-123
Net --> PS: Timeout (No response in 5s)
note right of PS: Start Retry Timer\n(Exponential Backoff)
... 1 minute later ...
PS -> Net: POST /webhooks\nevent_id=abc-123
Net -> CRM: Deliver Request
CRM -> CRM: Check event_id abc-123
alt Event not processed before
CRM -> CRM: Save event_id to cache
CRM -> CRM: Update Customer Record
CRM --> Net: 200 OK
else Duplicate delivery
CRM --> Net: 200 OK (Idempotent)\nIgnore body
end
Net --> PS: Response Received
PS -> PS: Mark event as delivered
@enduml
Эта диаграмма демонстрирует важность разделения момента принятия события (acceptance) и момента завершения обработки (completion). CRM возвращает 200 сразу после записи в кэш, а не после полного обновления базы данных клиентов. Это предотвращает ложные таймауты при медленной обработке.
Таблица статусов и действий
Ниже приведена таблица, определяющая поведение обеих сторон в зависимости от полученного HTTP-статуса. Эта таблица должна стать частью технического задания и служить эталоном для написания unit-тестов.
| HTTP Статус | Смысл для Отправителя | Действие Отправителя | Смысл для Приёмника |
|---|---|---|---|
| 200 OK | Событие обработано | Отметить как delivered | Логическое завершение операции |
| 202 Accepted | Событие принято в очередь | Отметить как accepted (ожидать финального ack, если требуется) | Приём в буфер, обработка асинхронно |
| 400 Bad Request | Ошибка формата/валидации | НЕ повторять. Логировать ошибку | Payload не соответствует схеме |
| 401 Unauthorized | Ошибка авторизации | НЕ повторять. Проверить секрет | Неверный HMAC-подпись или API Key |
| 429 Too Many Requests | Лимит частоты превышен | Повторить с увеличенным интервалом (Respect Retry-After) | Слишком много запросов за единицу времени |
| 500 Internal Error | Внутренний сбой приёмника | Повторить (Exponential Backoff) | Ошибка в коде обработчика |
| Timeout | Нет ответа в установленное время | Повторить (Exponential Backoff) | Сеть или приложение зависло |
Безопасность и аутентификация
Webhook-эндпоинты должны быть защищены. Основные методы включают использование Secret Token (HMAC-SHA256 подпись тела запроса) или API Key в заголовке. При использовании HMAC отправитель вычисляет хеш тела запроса с общим секретом и передаёт его в заголовке X-Signature. Приёмник пересчитывает хеш и сравнивает. Это защищает от подделки событий злоумышленником, который перехватил трафик или знает URL эндпоинта. Также рекомендуется использовать HTTPS для защиты данных в transit. Важно не передавать чувствительные данные (пароли, CVV карт) в открытом виде в payload, даже если канал защищён. Данные должны быть минимально необходимыми для выполнения задачи.
Типичные ошибки проектирования
- Отсутствие Idempotency Key — если в payload нет уникального ID события, приёмник не может отличить повторную доставку от нового события. Это приводит к дублированию операций.
- Длинная синхронная обработка — если приёмник тратит 30 секунд на обработку и только потом отдаёт ответ, отправитель (с таймаутом 5 сек) решит, что доставка провалилась, и начнёт повторять. Результат: перегрузка приёмника дублями.
- Повтор на 4xx ошибки — автоматические ретраи на ошибки валидации (400) бесполезны и создают нагрузку. Ошибка в структуре не исчезнет сама собой.
- Неопределённый таймаут — если не указан таймаут чтения (read timeout), зависший приёмник может держать соединение открытым бесконечно, блокируя ресурсы отправителя.
Инструментарий для описания
Для создания такого контракта удобно использовать специализированные инструменты. Описание событий можно оформить в формате OpenAPI 3.0, определив компоненты схемы. Для визуализации потока данных используется PlantUML. Оба формата поддерживаются в редакторах helper-sa. Вы можете открыть редактор PlantUML, вставить приведённую выше диаграмму и адаптировать её под вашу архитектуру. Также полезно свериться с общим обзором стратегий интеграции в статье Sync vs Async Integration, чтобы убедиться, что webhook действительно подходит для вашего сценария (высокая частота событий, низкая критичность задержки).
Итог
Качественный webhook-контракт состоит из трёх частей: строгой схемы payload с обязательным event_id, прозрачной retry-политики с экспоненциальным бэкоффом и явного протокола подтверждения через HTTP-статусы. Внедрение идемпотентности на стороне приёмника защищает от побочных эффектов повторной доставки. Использование sequence-диаграмм и таблиц статусов делает ожидания обеих сторон однозначными, сокращая время на отладку и снижая риск потери данных. Начните с определения схемы события, затем опишите правила ретраев, и только потом реализуйте код отправителя и приёмника, тестируя оба конца по одному и тому же контракту.
