Вебхуки — 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": 2500000,
    "currency": "RUB",
    "destination": { "type": "card", "number": "2200000000000000" },
    "metadata": null,
    "failure_reason": null,
    "completed_at": "2026-06-02T18:34:11+00:00",
    "failed_at": null
  }
}

Событие webhook.test

Когда в кабинете мерчант нажимает «тест вебхука», Cashera отправляет на тот же callback_url с теми же заголовками X-Api-Key и X-Secret проверочное событие webhook.test. Оно служит только для проверки доставки и не относится ни к одному заказу.

{
  "event": "webhook.test",
  "test": {
    "sent_at": "2026-06-02T18:00:00+00:00"
  }
}

Допускайте неизвестные события

Не отклоняйте вебхук по жёсткому списку разрешённых типов. Обрабатывайте интересующие вас события (transaction.status_updated, payout.status_updated), а на неизвестные и на webhook.test просто отвечайте 2xx — список событий может расширяться.

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

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

Если доставка так и не удалась, состояние всегда можно получить запросом. По платежам — статус транзакции или поиск по external_id. По выплатам — статус выплаты, если вы сохранили uuid при создании, либо история выплат за нужный период, если не сохранили.

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

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

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

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