Вебхуки — Cashera Docs

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

Событие приходит POST-запросом на callback_url (платежа/выплаты или из настроек мерчанта).
Тело — JSON с типом события и объектом.
Запрос содержит заголовки X-Api-Key и X-Secret — обязательно проверяйте их подлинность.
Ответьте 2xx. Иначе доставка повторяется.

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

URL должен использовать HTTPS (порт 443) и указывать на публичный хост. Адреса вида localhost, *.local, *.internal и приватные IP отклоняются. Вебхуки уходят, только если в кабинете включены уведомления и задан секрет мерчанта.

Заголовки и аутентификация

Каждый вебхук содержит статические заголовки с вашими учётными данными:

Поле	Тип	Описание
`Content-Type`опц.	`string`	`application/json`
`X-Api-Key`опц.	`string`	Публичный ключ мерчанта (`pk_…`).
`X-Secret`опц.	`string`	Секрет мерчанта (`sk_…`). Сравните со своим сохранённым секретом.

Не логируйте X-Secret

Сравнивайте X-Api-Key и X-Secret с вашими значениями в постоянном времени и никогда не пишите секрет в логи, APM или трекеры ошибок. Подробно — на странице проверки подлинности.

Событие transaction.status_updated

{
  "event": "transaction.status_updated",
  "transaction": {
    "uuid": "9b1f2c4e-7a01-4b9d-8f1c-2eab57d90c11",
    "external_id": "order-10428",
    "status": "paid",
    "type": "deposit",
    "amount": 49900,
    "gross_amount": 49900,
    "net_amount": 48403,
    "currency": "RUB",
    "payment_method": "sbp",
    "paid_at": "2026-06-02T18:11:42+00:00"
  }
}

Событие payout.status_updated

{
  "event": "payout.status_updated",
  "payout": {
    "uuid": "7c2e5b91-0a44-4d12-9f3a-1be64c0d2255",
    "external_id": "withdraw-001",
    "status": "completed",
    "amount": 25000000,
    "currency": "USDT",
    "destination": { "type": "usdt_trc20", "address": "TM9...x7" },
    "metadata": null,
    "failure_reason": null,
    "completed_at": "2026-06-02T18:34:11+00:00",
    "failed_at": null
  }
}

Доставка и повторы

Вебхук отправляется только при реальной смене статуса (дубли провайдера не пересылаются).
При неуспехе доставка повторяется до 3 раз с интервалом около 5 минут.
Ответ 4xx считается ошибкой конфигурации — повторов не будет, доставка фиксируется как неуспешная.
Ответы 5xx и сетевые сбои — повторяются.

Идемпотентность

Эндпоинт должен быть идемпотентным: один и тот же статус может прийти повторно. Используйте ключ uuid + status (для платежей — transaction.uuid + transaction.status, для выплат — payout.uuid + payout.status) и пропускайте уже обработанные события, возвращая 200.

Что считать подтверждением

Заказ оплачен только при transaction.status = paid; выплата исполнена только при payout.status = completed. Перед зачислением сверяйте сумму и валюту с вашими данными.