Интеграция webhook
Webhook сообщает о событии аккаунта на указанный URL. Это уведомление; актуальный статус проверяйте через GET транзакции.
Настроить получателя
В настройках Heth укажите принадлежащий вам URL, настройте секрет интеграции и включите доставку. Изменение URL меняет получателя событий аккаунта. Защитите endpoint и избегайте перенаправлений посторонним получателям. Настройка требует пользовательскую сессию; транзакционного API-ключа не обязательно достаточно.
Обработать уведомление
- Проверьте подпись webhook аккаунта и защиту от повторов по описанию ниже.
- Сохраните идентификаторы события и транзакции, удаляя чувствительные поля.
- Обрабатывайте идемпотентно: повторное или запоздавшее уведомление не должно создавать новый платёж.
- Получите транзакцию со своими реквизитами доступа и сверьте статус.
- Верните ответ, предусмотренный настроенным контрактом доставки.
Push браузера не является webhook и не гарантирует доставку. Этот обзор не обещает общий для всех интеграций порядок, интервалы повторов или формат авторизации. До включения боевой автоматизации получите действующий контракт доставки.
Формат доставки webhook аккаунта
Этот формат относится к webhook, настроенному в Heth. Другие callback-интеграции могут иметь иной контракт.
При непустом секрете webhook передаются x-webhook-signature (hex HMAC-SHA256), x-webhook-timestamp (Unix seconds) и x-webhook-event-id. Проверяйте HMAC от timestamp + "." + точных исходных байтов HTTP-тела с настроенным секретом: до проверки нельзя разобрать JSON и сериализовать заново. Сверяйте timestamp подписанного тела с заголовком, отклоняйте расхождение часов больше 5 минут, сравнивайте подписи за постоянное время и исключайте повторную обработку по event_id. При повторе event_id сохраняется, timestamp и подпись обновляются. Без настроенного секрета заголовков подписи может не быть; до автоматизации задайте секрет.
hex(HMAC-SHA256(secret, timestamp + "." + raw_body))
Конверт содержит event_id, timestamp, type и data. В транзакционных событиях аккаунта data содержит tx_id, txid, type, status, amount, currency и event_type. amount может быть JSON-целым: используйте разбор без потери точности. Донат может добавлять объект donation. После проверки и сохранения события отвечайте HTTP 2xx; повторный проверенный event_id не должен повторять бизнес-действие. Даже после подписанного уведомления сверяйте транзакцию через GET.