Webhook Проверка подписи и идемпотентность

Эта страница следует Agent Java SDK WEBHOOKS.md при фиксации fa6c7b6. Это обновление предназначено только для документации; новый артефакт SDK, содержащий вспомогательные методы предупреждений, не был выпущен.

Все четыре типа событий используют один обратный вызов продавца URL и отправляются телом event. Видеть Webhook События и предупреждения о ликвидации для полей событий и примеров полезной нагрузки.

Webhook заголовки

timestamp + nonce + rawBody

Идемпотентность событий

Сохранение дедупликации внутри продавца и области environment атомарно с бизнес-обработкой. Различные значения notificationId идентифицируют независимые уведомления FIRST / UPGRADE / REMINDER; не удаляйте уведомления путем группировки по пользователю, эпизоду или eventType. Пустой ключ идемпотентности не может использоваться для дедупликации. SDK возвращает только вспомогательный ключ; он не сохраняется и не обрабатывает бизнес-данные. Зафиксируйте ту же идентичность с другим телом как конфликт; не перезаписывайте обработанное тело.

Проверка и получение подписи

Используйте секрет продавца API для вычисления шестнадцатеричной подписи HMAC-SHA256 шестнадцатеричной подписи timestamp + nonce + rawBody. Проверьте исходные полученные байты; не форматируйте JSON, не переименовывайте поля и не повторно сериализуйте тело.

Сначала проверьте подпись, затем проверьте временное окно (рекомендуется ±300 секунд), продавца и среду. Затем извлеките идентификатор идемпотентности и надежно обработайте уведомление. Сохранять неизвестные значения событий для диагностики; никогда не интерпретируйте их как успех фонда. Помощник по проверке не выполняет проверки временного окна, владения или постоянную дедупликацию.

Верните HTTP 2xx после завершения обработки или подтверждения идентичности дубликата; вернуть не-2xx в случае неудачи. Отправитель предупреждения имеет 5-секундный тайм-аут HTTP и не более 8 попыток. Повторные попытки сохраняют замороженное тело; изменяются только временная метка подписи и nonce. Отвечайте сразу после надежного принятия; длительная деловая работа может использовать собственные постоянные задачи продавца.

Уведомления продавца не зависят от онлайн-статуса пользователя. Нажатия пользователей платформы осуществляются только в режиме онлайн с максимальными усилиями, без повторного воспроизведения в автономном режиме; на первом этапе нет почтового ящика для уведомлений.

Успешные ответы и прекращение повторных попыток

Обратные вызовы средств и предупреждения о ликвидации используют **только код состояния HTTP для определения успешности доставки. Отправитель не интерпретирует тело ответа code, success, result или message и не требует фиксированного ответа OK / success.

Тело ответа может быть пустым, текстовым или JSON. Примеры полей result являются информационными для продавца, а не требованиями протокола. 202 Accepted также останавливает повторные попытки платформы, поэтому возвращайте его только после надежного сохранения уведомления в постоянной очереди задач продавца, а не просто запуская асинхронную задачу в памяти.

Примеры успешных ответов

После завершения бизнес-обработки или после того, как уведомление было надежно сохранено в собственной очереди ожидания продавца:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

Когда тело ответа не требуется:

HTTP/1.1 204 No Content

Для уже обработанного уведомления с идентичным телом пропустите дублирующую бизнес-обработку и по-прежнему возвращайте 2xx:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

Примеры реагирования на отказ

Если база данных временно недоступна и продавец не завершил обработку и не сохранил уведомление, верните значение, отличное от 2xx, чтобы платформа могла повторить попытку:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

Отклонить недействительную подпись без обновления бизнес-данных или успешных записей дедупликации:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

Эти органы реагирования не меняют решения о повторных попытках. Не ожидайте, что код 401 или 409 навсегда прекратит повторные попытки; изучите подпись, содержимое уведомления или конфигурацию продавца.

Неправильный пример: следующий ответ по-прежнему считается успешной доставкой. Платформа не будет повторять попытку из-за success:false.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

Если платформа или глобальный обработчик исключений оборачивает бизнес-сбои в HTTP 200, явно установите правильный статус сбоя в конечной точке обратного вызова.

Надежное подтверждение и дублированная доставка

Рекомендуемый ордер: проверьте подпись и проверьте время/продавца/среду → извлеките идентификатор идемпотентности → обработайте бизнес-данные и успешные записи дедупликации в транзакции или надежно сохраните ожидающую задачу → верните 200/204 после успешной фиксации. Не возвращайте 2xx и не отмечайте уведомление как обработанное до успешной записи в базу данных.

Двойная доставка все еще может произойти после успешной обработки продавцом: ответ может быть потерян или платформа может получить 2xx, но не сохраниться SUCCESS. HTTP обратные вызовы не гарантируют единовременную доставку. Сохранять дедупликацию внутри продавца и в области environment. Средства используют orderType:orderId:targetStatus; в предупреждениях используйте liquidation.warning:notificationId. Для идентичного уже обработанного тела вернуть 2хх без зачисления средств и повторного напоминания. Для того же идентификатора с другим телом запишите конфликт и верните значение, отличное от 2xx; не перезаписывайте исходную запись.

Успешное подтверждение означает, что продавец получил/обработал уведомление, а не то, что операция с средствами прошла успешно. После записи действительного уведомления о средствах с помощью targetStatus=FAILED также верните 2xx; отказ от заказа не является основанием для отказа в подтверждении уведомления.

Финансирование и границы окружающей среды

Исходный поток передачи Контракта webhook и queryOrder не применяется автоматически к Финансированию. Подтвердите операции финансирования, используя queryWalletTransfer и исходную среду заказа. Финансирование использует status; в исходных ответах на передачу контракта используется orderStatus. Успешный ответ HTTP или code=0 сам по себе не доказывает, что средства были переведены.

Явные уведомления о передаче смоделированного контракта включают environment=SIMULATED. Сначала проверьте необработанное тело, затем сверьте пользователя, сумму, идентификатор заказа и среду с сохраненным локальным бизнес-заказом.

Руководство по восстановлению средств · Руководство по окружающей среде