payout.succeeded
Выгрузка исполнителю успешно завершена, средства зачислены. В теле — сумма, валюта и идентификатор получателя.
Схема полей
Справочник
Webhooks события, которые текут к вам
Cobalflow отправляет HTTP-уведомления о каждом изменении статуса платежа в вашу систему. Ниже — полный перечень событий, способ проверить подлинность запроса и политика повторных попыток при недоступности вашего эндпоинта.
Формат события
Что приходит в теле запроса
Каждый вебхук — это POST-запрос с JSON-телом. Поле id уникально для каждого события, а created_at — метка времени в формате ISO 8601. Ответьте кодом 2xx в течение 5 секунд, чтобы остановить повторные попытки.
Пример тела событияapplication/json
idevt_9f2a7c14
typepayout.succeeded
created_at2025-05-14T09:22:41Z
data.amount12 400
data.currencyRUB
Типы событий
Перечень событий
Подпишитесь на интересующие вас события при настройке эндпоинта. События выгрузки и приёма платежей разведены по отдельным типам — вы получаете только то, что нужно.
payout.failed
Выгрузка не прошла. Поле error_code укажет причину: insufficient_funds, invalid_account, bank_rejected.
Коды ошибокpayout.processing
Операция принята и обрабатывается банком-корреспондентом. Отправляется один раз в момент старта обработки.
Подробнееcharge.succeeded
Платёж от клиента успешно принят. В теле — метод оплаты, сумма и ссылка на чек.
Схема полейcharge.disputed
Клиент оспорил платёж. Событие приходит в течение 24 часов после подачи чарджа-запроса.
Подробнееledger.balance_updated
Изменился остаток на счёте казначейства. Отправляется при каждом зачислении или выводе средств.
Подробнее
Безопасность
Проверка HMAC-подписи
Каждый вебхук несёт заголовок X-Cobalflow-Signature — это HMAC-SHA256 от тела запроса, вычисленный с вашим секретным ключом. Проверьте подпись до обработки данных, чтобы отклонить поддельные запросы.
Как проверить подпись
Возьмите тело входящего POST-запроса, ваш секретный ключ вебхука (начинается с whsec_) и вычислите HMAC-SHA256. Результат сравните с содержимым заголовка X-Cobalflow-Signature в формате sha256=<hex>. Используйте константное сравнение строк, чтобы избежать атаки по времени.
Пример на Node.js
crypto.createHmac('sha256', secret).update(rawBody).digest('hex') — сравните с заголовком. Если не совпадает, верните 401 Unauthorized и не обрабатывайте тело.
Где взять секретный ключ
Секрет генерируется автоматически при создании вебхук-эндпоинта в консоли. Его можно пересоздать в любой момент — старые подписи перестанут валидироваться. Ключ отображается один раз, повторно получить его нельзя.
Доставка
Политика повторных попыток
Если ваш эндпоинт не ответил кодом 2xx в течение 5 секунд или вернул ошибку, Cobalflow автоматически повторяет доставку. Мы не теряем события — каждое событие гарантированно доставляется или помечается как не доставленное.
8 раз
Повторных попыток в течение 24 часов
1 мин
Интервал между первой и второй попыткой
5 сек
Тайм-аут ожидания ответа от вашего сервера
24 ч
Общее окно доставки перед отменой
График повторных попытокэкспоненциальный бэкофф
Попытка 1+1 мин
Попытка 2+5 мин
Попытка 3+30 мин
Попытка 4+2 ч
Попытки 5–8каждые 4 ч
Начните принимать события
Создайте вебхук-эндпоинт в консоли, получите секретный ключ и подключите проверку подписи. Песочница шлёт тестовые события мгновенно — без реальных платежей.
Вопросы
Что чаще всего спрашивают
Да. При создании вебхук-эндпоинта вы выбираете конкретные типы событий. Мы отправляем только те, на которые вы подписались.
После 8 попыток событие помечается как не доставленное. Вы можете вручную триггерить повторную доставку из консоли или через API-метод resend_event.
Вебхуки отправляются только на публичные HTTPS-эндпоинты. Для внутренней инфраструктуры используйте собственный ретранслятор с публичным адресом.
Ключ не обновляется автоматически. Вы можете пересоздать его вручную в любой момент — старые подписи перестанут валидироваться немедленно.