Верифікація та ідемпотентність підпису вебхука

Вебхуки повідомляють партнерський бекенд про асинхронні зміни бізнес-стану. Оскільки доставка може бути повторною, кожен отримувач повинен перевірити підпис перед аналізом довірених даних і обробити подію ідемпотентно.

Заголовки Webhook

Заголовок	Опис
X-Агент-Часова Мітка	Тайммарк Unix за секунди.
X-Agent-Nonce	Захист від повтору не так.
X-Агент-підпис	HMAC-SHA256 підпис.

timestamp + nonce + rawBody

Використовуйте точне сире тіло запиту, отримане протягом HTTP , при відновленні підписаного значення. Спочатку парсинг і повторна серіалізація JSON можуть змінити пробіл або ордер полів і отримати інший підпис.

Потік верифікації

Прочитайте часову мітку, нонс і підписні заголовки.
Захопити незмінене сирий запит.
Будуйте timestamp + nonce + rawBody.
Розрахуйте HMAC-SHA256 з партнером API секрет.
Порівняйте розраховані та отримані підписи за допомогою порівняння з постійним часом.
Застосовуйте затверджені перевірки свіжості та неповторного використання.
Розбирати та обробляти подію лише після успішної перевірки.

Коли доступний офіційний Agent SDK -верифікатор, використовуйте його замість того, щоб підтримувати незалежний код підпису.

Ідемпотентність порядку

Випадок	Керованість
Початковий запит на переведення	Створіть унікальний у світі agentOrderNo.
HTTP тайм-аут	Запитайте оригінальний agentOrderNo перед створенням нового.
PROCESSING відповідь	Зачекайте на статус замовлення вебхука або запиту.
Повторюваний вебхук	Дедуплікація за ключем ідемпотентності та кінцевим статусом.

Рекомендований запис ідемпотентності

Зберігайте достатньо інформації, щоб розпізнати повторну доставку і безпечно відновити її:

Поле	Мета
Ключ події або бізнесу	Унікально ідентифікує сповіщення або операцію.
Номер замовлення партнера	Пов’язує подію з початковим запитом.
Хеш корисного навантаження	Допомагає виявити суперечливі повторювані корисні навантаження.
Поточний стан обробки	Розрізняє отриману, обробку, успішну та невдалу роботу.
Остаточний статус бізнесу	Запобігає двічі застосування термінальної дії.
Оброблена часова мітка	Підтримує політику розслідування та утримання.

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

Правило тайм-ауту та повторної спроби

Тайм-аут HTTP не доводить, що початковий запит не провалився. Запит до операції за допомогою оригінального agentOrderNoабо зачекайте на її веб-гак, перш ніж вирішувати, чи потрібна ще одна дія. Створення нового номера бізнес-замовлення після кожного тайм-ауту може спричинити дублювання рухів фонду.

Чек-лист виробництва

Перевірити підпис перед JSON парсінгом або бізнес-обробкою.
Зберігати сирий корпус незалежно від розборованого корисного навантаження.
Відхилити застарілі або повторні запити відповідно до затвердженої політики інтеграції.
Зробити обробку подій безпечною для повторної та поза порядком доставки.
Ідентифікатори подій журналу, номери замовлень партнера, результати обробки та час запиту.
Редагувати секрети та значення підписів із журналів і підтримуючих вкладень.

Секрети та HMAC підписання

Захистіть API секрет, який використовується для перевірки запитів і вебхуків.

Agent SDK Огляд

Перегляньте повний робочий процес інтеграції бекенду.

SDK Усунення несправностей