Обзор
Система webhook-уведомлений Meridian обеспечивает надежную доставку событий об изменении статуса инвойсов на ваш endpoint.События webhook
Типы событий
Webhook отправляются при следующих изменениях статуса инвойса:Формат webhook запроса
HTTP запрос
Заголовки
string
HMAC-SHA256 подпись тела запроса в hex-форматеИспользуйте для проверки подлинности webhook (см. раздел Верификация подписи)
string
Тип события (например,
invoice.paid, invoice.expired)Позволяет быстро определить тип события без парсинга телаstring
Уникальный ID доставки webhook (UUID)Используйте для идемпотентности - сохраняйте обработанные ID, чтобы не обрабатывать дубликаты
Retry стратегия
Автоматические повторы
Meridian автоматически повторяет неудачные доставки webhook:
После 3 неудачных попыток webhook перемещается в Dead Letter Queue (DLQ) для ручной проверки.
Когда происходит retry
Тело webhook запроса
Для событий инвойса
Для событий тело запроса содержит полный объект инвойса c новым статусом: Пример дляdirection: "in" (входящий платеж):
direction: "out" (исходящий платеж) со статусом paid:
Поле
newStatusExpiresAt: Для OUT инвойсов указывает время истечения заявки в статусе "new" (5 часов с момента создания). После истечения средства возвращаются на баланс мерчанта.Поле transactionProofUrl: Для OUT инвойсов в статусах review или paid включает presigned S3 URL (время действия 7 дней) для доступа к доказательству оплаты, загруженному трейдером.Для событий спора
Для событий тело запроса содержит полный объект аппеляции с новым статусом:Верификация подписи
Алгоритм подписи
Meridian подписывает каждый webhook запрос используя HMAC-SHA256 для обеспечения подлинности и целостности данных. Параметры алгоритма:- Алгоритм: HMAC-SHA256
- Секретный ключ: Ваш
notificationToken(32-255 символов) - Входные данные: JSON тело запроса (без модификаций)
- Выходной формат: Hex-кодированная строка
- Заголовок:
X-Webhook-Signature