Webhooks і SDKs
Webhooks сповіщати серверну частину про ділові події. Використовуйте їх разом із API запитами, щоб затримка або відсутність доставки не залишала ваші записи невирішеними.
Перевірте перед обробкою
Поточна доставка включає X-Webhook-Signature і X-Webhook-Timestamp. У підписі використовується HMAC-SHA256 над текстом заголовка позначки часу, крапка та точне необроблене тіло запиту. Його значення заголовка має вигляд sha256=<HEX_SIGNATURE>.
- Зберігайте необроблене тіло перед розбором JSON.
- Перевірте мітку часу, використовуючи погоджений допуск годинника.
- Перевірте підпис із секретом webhook за допомогою порівняння постійного часу.
- Тільки після цього інтерпретуйте корисне навантаження та оновлюйте бізнес-записи.
Переформатування аналізованого JSON перед перевіркою змінює підписані байти. Підтвердження Webhook використовує секрет webhook, а не секрет запиту API або ключ авторизації клієнта.
Зберігати та видаляти дублікати
Конверт містить event_id, event_type, created_at, tenant_id і data. Для звичайної доставки подій використовуйте перевірену ідентифікацію події з кінцевою точкою або контекстом робочої області, щоб запобігти повторному застосуванню. Зберігайте це рішення атомарно з отриманим бізнес-оновленням або надовго додайте перевірену подію до її підтвердження.
X-Webhook-Idempotency-Key також надається для звичайної доставки вихідних повідомлень. Це метадані доставки, а не незалежно підписане поле корисного навантаження. Не дозволяйте зміненому заголовку призводити до того, що одна й та сама перевірена подія двічі переміщує гроші. Тестові доставки та ручні операції можуть мати різні ідентифікатори або опускати цей заголовок.
Поверніть успішну відповідь після тривалого прийняття події. Розробка для дублікатів і подій із затримкою чи непорядком. Позначка часу доставки не є гарантованим часом виникнення бізнесу. Запитуйте основний ресурс, коли подія конфліктує з пізнішим відомим результатом.
Виберіть пакет інтеграції
Це області впровадження вихідного коду, а не підтвердження доступності реєстру пакетів або загального випуску. Отримайте відповідний пакет версії та інструкції з його встановлення під час реєстрації. Інші ресурси можуть потребувати прямих API дзвінків; не робіть висновок про повний API клієнт за наявністю пакета webhook.
Перевірте приймальний шлях
Перевірте дійсну доставку, змінене тіло, недійсний підпис, застарілу позначку часу, подію-дублікат і перезапуск приймача. Підтвердьте домовленості про повторну спробу та відтворення з інтеграційним середовищем. Відсутні зворотні виклики мають ініціювати узгодження, а не другий запит на зняття коштів.