Документация

Webhooks

Уведомления об изменении счетов, пополнений и выводов на ваш HTTPS-адрес в формате плоского JSON (camelCase, schemaVersion: 2).

Настройка

  1. Откройте настройки проекта.
  2. Перейдите в раздел «Интеграции».
  3. Укажите URL для уведомлений и сохраните настройки.
  4. Система создаст secret для проверки подлинности запросов.

Как это работает

  • При значимом изменении счёта, депозита или вывода система сохраняет состояние объекта с новой revision и формирует событие.
  • Atomic Pay отправляет на ваш URL POST-запрос с JSON-телом и подписью в заголовках.
  • Ваш сервер проверяет подпись по исходному телу, сохраняет событие и возвращает успешный ответ.
  • Если сервер не отвечает или возвращает 5xx, 408 или 429, доставка повторяется.
  • Дубликаты определяйте по eventUuid. Для нескольких событий одной сущности обрабатывайте самую новую revision.

Типы событий

typeeventType
invoiceinvoice.created, invoice.updated, invoice.partially_paid, invoice.completed, invoice.overpaid, invoice.expired, invoice.cancelled
depositdeposit.detected, deposit.confirmed, deposit.reorged, deposit.failed
payoutpayout.requested, payout.queued, payout.broadcasted, payout.confirmed, payout.failed, payout.cancelled

Общие поля

ПолеОписание
schemaVersionВерсия схемы webhook.
typeТип сущности: invoice, deposit или payout.
eventTypeСобытие, которое стало причиной отправки.
eventUuidУникальный идентификатор события. Не меняется при повторной доставке.
revisionВерсия состояния сущности. Увеличивается при изменениях.
uuidИдентификатор сущности или депозита.
projectUuidUUID проекта.
statusТекущее состояние сущности.
isFinalПризнак финального состояния.
occurredAtВремя события, UTC ISO 8601.
createdAtВремя создания сущности, UTC ISO 8601.
updatedAtВремя последнего изменения, UTC ISO 8601.

uuid идентифицирует сущность или депозит, а не само событие. Для идентификации события используйте eventUuid.

merchantAmount и комиссии

В webhook merchantAmount рассчитывается до вычета сетевой комиссии. В HTTP API это поле учитывает окончательные комиссии и до их расчёта может быть null — не сравнивайте значения напрямую.

Пример: deposit.confirmed

{
  "schemaVersion": 2,
  "type": "deposit",
  "eventType": "deposit.confirmed",
  "eventUuid": "9214fc7c-fc28-4397-b661-4dd873f811f9",
  "revision": 2,
  "uuid": "84e89df6-2801-46a8-a49f-e0b37a9775bd",
  "projectUuid": "73e68013-32f0-4248-95ac-46aed61e59b0",
  "depositSource": "project_wallet",
  "status": "confirmed",
  "isFinal": true,
  "depositResult": "accepted",
  "walletAddressUuid": "7d8bf964-9685-4065-ad77-9fc239a2c59f",
  "staticWalletUuid": null,
  "orderId": null,
  "fiatAmount": "1.5",
  "fiatCurrency": "USD",
  "fiatRate": "0.1",
  "address": "DA6Td5hJ7qXvPEsFBGcvMYeL7haGBESGri",
  "amount": "15.00000000",
  "merchantAmount": "14.85000000",
  "coinCode": "DOGE",
  "networkCode": "dogecoin",
  "confirmationsCurrent": 25,
  "confirmationsRequired": 20,
  "txid": "19b7f4d117a10b192307aa2f441dac60be799880ee6fda8c771696e5d3a360fc",
  "blockNumber": 6398234,
  "blockTimestamp": "2026-10-01T14:56:00.000Z",
  "detectedAt": "2026-10-01T14:56:29.831Z",
  "confirmedAt": "2026-10-01T15:20:00.000Z",
  "occurredAt": "2026-10-01T15:20:00.000Z",
  "createdAt": "2026-10-01T14:56:29.831Z",
  "updatedAt": "2026-10-01T15:20:00.000Z"
}
  • Депозит идентифицируйте по uuid. Не используйте txid как единственный идентификатор: одна транзакция может содержать несколько депозитов.
  • walletAddressUuid — идентификатор адреса, staticWalletUuid — идентификатор статического кошелька. Не путайте их.

Пример: payout.cancelled

{
  "type": "payout",
  "eventType": "payout.cancelled",
  "status": "cancelled",
  "isFinal": true,
  "coinCode": "USDT",
  "networkCode": "ethereum",
  "recipientAmount": "4.846587",
  "debitAmount": "4.951539"
}

Для payout поле serviceFee в webhook не передаётся.

Доставка

Ответ вашего сервераДействие
2xxУспешная доставка.
408, 429, 5xx, ошибки сети, таймаут, DNSПовторная доставка.
Остальные, включая 3xx и 409Окончательная ошибка, повтора не будет.

По умолчанию выполняется 10 попыток, после чего событие переходит в состояние dead_letter. Между попытками — экспоненциальная задержка со случайным jitter от 0 до +20%:

delay = min(60000, 2^max(1, n) × 1000) ms + jitter

Фиксированной задержки между попытками нет. Повторы прекращаются после успешного ответа или после последней попытки.

Обработка на вашей стороне

  • Возвращайте 2xx только после того, как событие надёжно сохранено.
  • Повторная доставка того же eventUuid не должна приводить к повторному зачислению — используйте его для дедупликации.
  • Порядок доставки не гарантируется: обрабатывайте дубликаты и события, пришедшие не по порядку.

Требования к URL

  • Протокол HTTPS.
  • Адрес доступен из интернета.
  • Не localhost и не приватный IP.
  • Без redirect — сервис не выполняет перенаправления.
← НазадИнформация о выводеДалее →Проверка подписи