Skip to main content

Обзор

Система 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) для ручной проверки.
Важно: Webhook считается успешным только при ответе 200-299. Любой другой код (включая 3xx, 4xx, 5xx) вызовет retry.

Когда происходит 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
Процесс генерации подписи:
Критически важно: Используйте точное JSON тело запроса для верификации без изменений форматирования, пробелов или порядка ключей. Любое изменение приведет к несовпадению подписи.

Примеры кода