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. За ідентичне вже оброблене тіло поверніть 2xx без зарахування коштів або повторного нагадування. Для того самого ідентифікатора з іншим тілом записати конфлікт і повернути не-2xx; не перезаписуйте вихідний запис.

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

Межі фінансування та середовища

Оригінальний потік передачі Контракту webhook і queryOrder не застосовуються автоматично до Фінансування. Підтвердьте операції фінансування за допомогою queryWalletTransfer і початкового середовища замовлення. Для фінансування використовується status; оригінальні відповіді щодо передачі контракту використовують orderStatus. Успішна HTTP відповідь або code=0 сама по собі не підтверджує переміщення коштів.

Явні сповіщення про симуляцію передачі контракту включають environment=SIMULATED. Спочатку перевірте необроблене тіло, а потім порівняйте користувача, суму, ідентифікатор замовлення та середовище зі збереженим місцевим бізнес-замовленням.

Інструкція з повернення фінансування · Керівництво по навколишньому середовищу