Уведомления

Вебхуки

Уведомления об изменении статуса счёта, которые Ketmus отправляет на ваш сервер.

При каждом изменении статуса счёта Ketmus отправляет POST-запрос с JSON на callback_url счёта или, если он не задан, на URL из настроек магазина. Запрос подписан секретом вебхуков — проверяйте подпись перед обработкой.

События

Событие	Когда приходит
`invoice.pending`	Клиент выбрал монету, адрес выдан
`invoice.confirming`	Транзакция найдена в сети, ожидаются подтверждения
`invoice.paid`	Счёт оплачен полностью
`invoice.paid_over`	Счёт оплачен с переплатой
`invoice.wrong_amount_waiting`	Пришла неполная сумма, счёт ждёт доплаты
`invoice.wrong_amount`	Счёт истёк с неполной оплатой
`invoice.expired`	Счёт истёк без оплаты
`invoice.cancelled`	Счёт отменён
`invoice.late_payment`	Платёж пришёл после истечения или отмены счёта
`static.payment`	Пополнение статического адреса
`webhook.test`	Тестовое событие из личного кабинета

Заголовки запроса

Заголовок	Пример	Описание
`content-type`	`application/json`	Тело — JSON
`user-agent`	`ketmus-webhooks/2.0`	Отправитель
`x-ketmus-event`	`invoice.paid`	Тип события
`x-ketmus-delivery`	`5d2b8e61-...`	Уникальный ID доставки, совпадает с `delivery_id` в теле
`x-ketmus-timestamp`	`1793787702`	Время отправки, Unix-секунды
`x-ketmus-signature`	`t=1793787702,v1=9f3c...`	Подпись HMAC-SHA512. → Проверка подписи

Тело уведомления

Тело содержит актуальное состояние счёта, а также поля event и delivery_id:

{
  "type": "invoice",
  "id": "8f0c6a52-3f7e-4b8e-9d61-2c4b0f8a1e7d",
  "order_id": "ORDER-1042",
  "status": "paid",
  "is_final": true,
  "late_payment": false,
  "price": {
    "amount": "25",
    "currency": "USD"
  },
  "payment": {
    "rail": "usdt_tron",
    "asset": "USDT",
    "network": "tron",
    "address": "TQ7nX4yVh3cE9v5G2kRZb8aWm1pLd6sFJt",
    "memo": null,
    "amount_due": "25.31",
    "amount_received": "25.31",
    "amount_confirmed": "25.31",
    "late_amount": "0",
    "rate": "1",
    "txids": [
      "a3f1c0e9d2b84f7c9e61d0b5a2c7e4f8b1d9c3a6e5f2b7d0c4a8e1f6b3d9c2a7"
    ]
  },
  "fee": {
    "bps": 125,
    "payer": "payer",
    "amount": "0.31",
    "merchant_amount": "25"
  },
  "pay_url": "https://app.ketmus.com/checkout/inv_5Kq2ZtR8wLmA",
  "metadata": {
    "user_id": "u_731"
  },
  "created_at": "2026-11-03T10:15:00.000Z",
  "expires_at": "2026-11-03T11:15:00.000Z",
  "paid_at": "2026-11-03T10:21:42.000Z",
  "event": "invoice.paid",
  "delivery_id": "5d2b8e61-0f4a-4c9b-a7e3-6b1d9f2c8a40"
}

Для события static.payment в теле дополнительно передаётся customer_id клиента, которому принадлежит адрес.

Как отвечать

Верните любой код 2xx в течение 10 секунд — доставка будет считаться успешной.
Тяжёлую обработку (выдачу товара, письма) выполняйте асинхронно, после ответа.
Редиректы не выполняются: ответ 3xx считается ошибкой. Указывайте окончательный HTTPS-адрес.

Повторная отправка

Если ваш сервер не ответил 2xx, Ketmus повторит отправку по расписанию: через 5 минут, 30 минут, 2 часа, 6 часов и 24 часа — всего до 6 попыток. История доставок и кнопка повторной отправки доступны в личном кабинете.

Идемпотентность и порядок

Одно событие может прийти несколько раз — сохраняйте delivery_id и пропускайте уже обработанные.
События могут прийти не по порядку. Ориентируйтесь на status и is_final в теле, а не на порядок получения.
Если сомневаетесь, запросите актуальное состояние: GET /invoices/{id}.

Вебхуки

#События

#Заголовки запроса

#Тело уведомления

#Как отвечать