Вебхуки

📦 Что такое вебхуки

Webhook — это способ, с помощью которого Monocrypt уведомляет ваш сервер о входящих событиях в реальном времени. Например, когда поступает депозит на адрес клиента или юнита, мы отправляем POST-запрос на ваш API-эндпоинт с подробностями транзакции.

---

⚙️ Настройка

Чтобы получать уведомления, вы должны предоставить Monocrypt ваш API route (endpoint), например:

https://your-domain.com/api/monocrypt/webhook

На этот адрес Monocrypt будет отправлять уведомления о входящих депозитах в формате application/json.

---

📨 Пример запроса

{
  "id": 32918,
  "txId": "d0e6bfa202c796190aec43071d268e24c506d139339d1a07f5dccbebc65eb09a",
  "amount": "10",
  "fee": null,
  "serviceFee": null,
  "addressFrom": "TEH22JTjF76B81XosER3wKSDB2s7DB3rWm",
  "walletFromName": null,
  "addressTo": "TW2BRbWXPa4C2L5Ax8aJY1oeMYf9aAhD46",
  "walletToName": null,
  "currency": "TRX",
  "network": "TRC20",
  "direction": "payin",
  "status": "submitted",
  "invoice": null,
  "client": {
    "id": 361,
    "createdAt": "2025-11-04T09:04:22.723Z",
    "updatedAt": "2025-11-04T09:04:22.723Z",
    "clientId": 361,
    "uuid": "28320c04-a687-4af2-8e47-1b30e747ed82",
    "email": "[email protected]",
    "name": "test",
    "rootUnitId": 49,
    "unitId": 239,
    "isExternalParam": false,
    "unit": {}
  },
  "unit": null,
  "riskScore": 0,
  "createdAt": "2025-11-04T09:04:42.855Z",
  "updatedAt": "2025-11-04T09:05:19.075Z"
}

---

🧠 Логика структуры

• Если транзакция поступила на клиента, в теле будет заполнено поле client.

• Если транзакция поступила на юнит, будет заполнено поле unit.

• Если транзакция поступила на инвойс, будет заполнено поле invoice.

• Если транзакция прошла от клиента/инвойса на юнит (например, оплата инвойса) — будут присутствовать оба поля: client/i и unit.

Это позволяет точно понять источник и назначение каждой транзакции. Все структуры (client, unit, invoice) описаны в соответствующих разделах документации.

---

🚀 Пример обработки на вашей стороне

Рекомендуется принимать webhook максимально быстро и возвращать HTTP 200 OK, не дожидаясь внутренней обработки. Саму бизнес-логику можно выполнять асинхронно (через очередь, воркер и т.п.).

// Пример Express.js
app.post("/api/monocrypt/webhook", async (req, res) => {
  const payload = req.body;

  // ✅ Подтверждаем приём, чтобы Monocrypt не повторял запрос
  res.sendStatus(200);

  // ⚙️ Дальше можно обработать данные асинхронно
  await processDeposit(payload);
});

---

📡 Политика доставки вебхуков

Monocrypt гарантирует надёжную доставку уведомлений о событиях. Система ожидает от вашего сервера ответ HTTP 200 OK. Любой другой код ответа, таймаут или ошибка сети считается ошибкой доставки.

Если доставка не удалась — будет выполнена повторная отправка с экспоненциальной задержкой:

Попытка	Задержка
1	30 секунд
2	1 минута
3	2 минуты
4	4 минуты
5	8 минут

---

📎 Важные замечания

⚠️ Тип запроса: Все вебхуки отправляются через POST с Content-Type: application/json.

⚠️ Дубликаты: Возможна повторная отправка одного и того же события (например, при сетевых сбоях). Ваш сервер должен быть идемпотентным, т.е. повторное получение одинакового webhook-а не должно вызывать побочных эффектов. Для этого можно проверять уникальный txId или id.

⚠️ Время обработки: Старайтесь как можно быстрее возвращать 200 OK. Если необходимо выполнить длительную операцию — запишите событие в очередь (RabbitMQ, Redis, Kafka и т.п.) и обработайте позже.

⚠️ Важно: Если ваш сервер по какой-либо причине не успел принять или обработать POST-запрос за время всех повторных попыток, вам необходимо самостоятельно запросить историю транзакций за пропущенный период (через GET /v1/transactions) и восстановить все недостающие события.

Таким образом, вы сможете гарантировать целостность данных и не потеряете информацию о поступивших депозитах.

---