B2B Webhooks

Партнёр подписывается на события managed customer'ов: KYC-результаты, статусы платежей. Finance OS пушит HMAC-подписанные POST'ы на указанные URL с retry-логикой.

События

Name	Required	Description
`customer.created`	optional	Customer создан (для аудита).
`customer.kyc.processing`	optional	Документы загружены, идёт проверка.
`customer.kyc.verified`	optional	KYC успешно пройден. Платежи разрешены.
`customer.kyc.rejected`	optional	Документы отклонены. Причина в payload.
`payment.buy.completed`	optional	СБП-платёж зачислен, USDT кредитован.
`payment.buy.failed`	optional	Платёж не прошёл.
`payment.sell.completed`	optional	СБП-выплата отправлена.
`payment.sell.failed`	optional	Выплата не прошла, locked возвращён в available.
`payment.withdraw.completed`	optional	Crypto withdraw подтверждён в сети.
`payment.withdraw.failed`	optional	Withdraw не прошёл.
`payment.deposit.confirmed`	optional	Входящий крипто-депозит подтверждён в сети.
`webhook.test`	optional	Тестовое событие (отправляется через `/test`).

POST /api/v1/webhooks

⚷ Bearer Token

Зарегистрировать endpoint

События).'], ]" />

Responses

{
  "data": {
    "id": 42,
    "url": "https://your-app.com/webhooks/finos",
    "events": ["customer.kyc.verified", "payment.buy.completed"],
    "env": "live",
    "active": true,
    "secret_last4": "wxyz",
    "created_at": "2026-05-27T14:23:00.000000Z"
  },
  "secret": "whsec_aBc1234567890DefGhIjKlMnOpQrStUvWxYz1234567890",
  "notice": "Save this secret now — it will not be shown again. Use it to verify the X-FinOs-Signature header on incoming webhooks."
}

⚠

Секрет показывается ОДИН РАЗ

После 201 Finance OS хранит секрет в зашифрованном виде. Если потеряли — POST /webhooks/{id}/rotate-secret сгенерирует новый (старый инвалидируется немедленно).

Формат payload

{
  "id": "evt_5f8d7a3c-1234-4567-89ab-cdef01234567",
  "type": "customer.kyc.verified",
  "created_at": "2026-05-27T14:23:00+00:00",
  "env": "live",
  "data": {
    "customer_uuid": "5f8d7a3c-...",
    "external_id": "user-42",
    "kyc_status": "verified",
    "kyc_level": 2,
    "kyc_rejection_reason": null
  }
}

HTTP-заголовки на запросе:

Content-Type: application/json
X-FinOs-Signature: sha256=<hmac>
X-FinOs-Event: customer.kyc.verified
X-FinOs-Webhook-Id: 42
User-Agent: Finance-OS-Webhooks/1.0

Верификация подписи

HMAC-SHA256 от raw body с секретом подписки. Всегда проверяйте подпись на стороне партнёра перед обработкой события — иначе риск injection-атак.

⊘

Constant-time сравнение

Используйте hash_equals (PHP), crypto.timingSafeEqual (Node), hmac.compare_digest (Python) — не === и не строковые сравнения, иначе атака по времени может вытащить секрет.

Retry-логика

Если ваш endpoint не вернул 2xx в течение 10 секунд, Finance OS повторяет:

1-я повторная попытка — через 30 секунд
2-я — через 5 минут
3-я — через 30 минут
4-я — через 6 часов
5-я — через 24 часа

После 5 неуспехов событие помечается как failed. Счётчики delivery_count и failure_count доступны в GET /webhooks.

Идемпотентная обработка

Каждое событие имеет уникальный id (evt_*). Сохраняйте обработанные ID и пропускайте повторы — это защитит от двойной обработки при retry.

Тестовый endpoint

POST /api/v1/webhooks/{id}/test