Перейти к навигации

Webhooks и SDKs

Просмотр в формате Markdown

Webhooks уведомляйте свой сервер о деловых событиях. Используйте их вместе с запросами API, чтобы задержка или отсутствие доставки не оставляли ваши записи неразрешенными.

Проверьте перед обработкой

Текущая поставка включает X-Webhook-Signature и X-Webhook-Timestamp. В подписи используются HMAC-SHA256 поверх текста заголовка метки времени, точки и точного необработанного тела запроса. Значение его заголовка имеет вид sha256=<HEX_SIGNATURE>.

  1. Сохраните необработанное тело перед анализом JSON.
  2. Проверьте метку времени, используя согласованный допуск часов.
  3. Проверьте подпись с помощью секрета webhook с помощью сравнения в постоянное время.
  4. Только после этого интерпретируйте полезную нагрузку и обновляйте бизнес-записи.

Переформатирование синтаксического анализа JSON перед проверкой изменяет подписанные байты. При проверке Webhook используется секрет webhook, а не секрет запроса API или ключ авторизации клиента.

Хранение и дедупликация

Конверт включает в себя event_id, event_type, created_at, tenant_id и data. Для обычной доставки событий используйте проверенный идентификатор события с контекстом конечной точки или рабочей области, чтобы предотвратить повторное применение. Сохраняйте это решение атомарно с результирующим бизнес-обновлением или надолго поместите проверенное событие в очередь перед его подтверждением.

X-Webhook-Idempotency-Key также предоставляется для обычной доставки исходящих сообщений. Это метаданные доставки, а не независимо подписанное поле полезной нагрузки. Не позволяйте измененному заголовку привести к тому, что одно и то же проверенное событие приведет к двойному перемещению денег. Тестовые поставки и ручные операции могут иметь разные идентификаторы или не включать этот заголовок.

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

Выберите пакет интеграции

Семейство пакетовТекущий объем реализации
Go и Python API SDKsАдрес, ресурсы для ввода и вывода средств, подписание запросов и сопутствующие помощники.
Go, Node.js и помощники Python webhookWebhook помощники по проверке подписи и интеграции с платформой

Это области реализации исходного кода, а не подтверждение доступности реестра пакетов или общего выпуска. Получите пакет соответствующей версии и инструкции по его установке во время адаптации. Другие ресурсы могут потребовать прямых вызовов API; не делайте вывод о полноценности клиента API по наличию пакета webhook.

Проверьте путь получения

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