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