Вебхуки
События сети на ваш адрес: конверт, подпись с меткой времени и повторы доставки.
Recca сообщает о событиях сети на ваш адрес. Каждое тело подписано HMAC-SHA256, в подписи — метка времени.
Включение
Адрес приёма задаётся в кабинете на странице «Вебхуки» организации: только HTTPS, адреса внутренних сетей и localhost не принимаются. Секрет подписи выдаётся там же.
Машинным путём CPA-сети адрес задаёт PUT /federation/v1/cpa/self/webhook (право cpa:self:write): секрет приходит в ответе на первый вызов или при rotate_secret, повторный вызов его не возвращает — сохраните сразу.
Конверт
Тело одно на все события:
{
"event_id": "fwd_01K5...",
"event_type": "cpa.conversion.approved",
"event_version": "1",
"organization_id": "org_01K5...",
"occurred_at": "2026-10-08T10:00:00.000Z",
"delivered_at": "2026-10-08T10:00:03.120Z",
"data": { ... }
}
event_id — идентификатор доставки: он не меняется при повторах, по нему удобно отсекать дубли. Тот же идентификатор приходит заголовком X-Recca-Delivery-Id. occurred_at — когда случилось событие, delivered_at — когда отправлено; у событий cpa.* первое есть, у остальных его нет. Повторы сдвигают delivered_at на часы, а occurred_at не меняется: сверяйтесь по нему, иначе вчерашняя конверсия попадёт в сегодняшний отчёт. Заголовки запроса — X-Recca-Signature, X-Recca-Delivery-Id и X-Recca-Event. Таймаут ответа — 10 секунд.
Проверка подписи
X-Recca-Signature: t=<unix-секунды>,v1=<hex(HMAC-SHA256(secret, "<t>.<сырое тело>"))>
Подписывается строка «метка времени, точка, тело запроса байт в байт» — разбирать JSON до проверки нельзя. Запросы с меткой старше пяти минут отклоняйте: так перехваченную доставку не воспроизвести.
app.post(
"/api/recca/webhook",
express.raw({ type: "application/json" }), // ВАЖНО: сырое тело
(req, res) => {
const m = /t=(\d+),v1=([0-9a-f]{64})/i.exec(req.header("X-Recca-Signature") || "")
if (!m) return res.status(401).end()
const expected = crypto
.createHmac("sha256", process.env.RECCA_WEBHOOK_SECRET)
.update(m[1] + "." + req.body.toString("utf-8"))
.digest("hex")
const fresh = Math.abs(Date.now() / 1000 - Number(m[1])) <= 300
const ok = crypto.timingSafeEqual(Buffer.from(m[2], "hex"), Buffer.from(expected, "hex"))
if (!fresh || !ok) return res.status(401).end()
const event = JSON.parse(req.body.toString("utf-8"))
// разбор по event.event_type; отвечайте 2xx быстро
res.json({ received: true })
}
)
Каталог событий
| Событие | Когда приходит | Поля data |
|---|---|---|
lead.created | Принята заявка (POST /federation/v1/leads). | lead_id, referrer_user_id, deeplink_id, external_id, lead_source, contact, metadata, created_at |
bonus.approved | Начисленный бонус подтверждён и стал доступен. | bonus_transaction_id, user_id, amount_rub, source_type, source_id, approved_at |
conversion.cascaded | Конверсия принята (POST /federation/v1/conversions), вознаграждение распределено по цепочке. | conversion_id, external_id, event_type, amount_rub, cascade_amount_rub, cascade_legs_count, cascade_legs |
conversion.reversed | Конверсия отменена или возвращена, начисленное списывается. | conversion_id, external_id, status, reversed_amount_rub, fully_reversed, reversed_legs, unreversed_legs, reason |
cpa.conversion.approved | CPA-сеть: холд конверсии дозрел, вознаграждение доступно партнёру. | external_id, goal, payout_rub, status, partner_external_id, occurred_at |
cpa.conversion.declined | CPA-сеть: конверсия отклонена. | external_id, goal, payout_rub, status, partner_external_id, occurred_at |
cpa.conversion.reversed | CPA-сеть: подтверждённая конверсия отменена. | external_id, goal, payout_rub, status, partner_external_id, occurred_at |
cpa.payout.paid | CPA-сеть: оператор отметил выплату выплаченной. | payout_id, amount_rub, partner_external_id, paid_at |
Суммы — в рублях (amount_rub, payout_rub). Состав событий может пополняться новыми полями: разбирайте тело терпимо к лишним ключам.
События cpa.* отправляются только организациям с подключённым продуктом «CPA-сеть». Они нужны, чтобы не опрашивать API: холд дозревает по нашему расписанию, а выплату отмечает человек в кабинете оператора — ни то, ни другое не является ответом на ваш запрос.
declinedиreversed— два события при одном статусе конверсииdeclined. Различие важно для учёта: в первом случае партнёру деньги не начисляли вовсе, во втором начислили и вернули.payout_idуcpa.payout.paid— идентификатор заявки на выплату (cpareq_…), которую вернулPOST /federation/v1/cpa/payouts. Заявка может списываться с нескольких кошельков партнёра; событие приходит один раз — когда оплачена последняя часть.- В событиях нет персональных данных: партнёр назван вашим
partner_external_id, имени, почты и телефона у Recca нет.
Повторы и идемпотентность
Доставка считается успешной при ответе 2xx. Любой другой ответ или таймаут — повтор с паузами 1 минута, 5 минут, 15 минут, 1 час, 6 часов; всего шесть попыток. После шестой неудачи событие уходит в очередь недоставленных, а в журнале аудита организации появляется запись «webhook.delivery_dlq».
Событие может прийти больше одного раза: храните уже обработанные event_id (достаточно 30 суток) и повторные пропускайте.
Рекомендации по приёму
- Отвечайте быстро (до 10 секунд): проверьте подпись и дубль, верните
2xx, а тяжёлую работу сделайте асинхронно. - Проверяйте подпись до разбора: пока подпись не сошлась,
event_typeдоверия не заслуживает. - Дедуплицируйте по
event_id(илиX-Recca-Delivery-Id): доставка «минимум один раз», и дубли случаются. - Не отвечайте
5xxна то, что вы не хотите обрабатывать: верните2xxи отбросьте событие. Ответ5xxзапустит повторы, которые мы не можем отменить. - Смените секрет, когда уходит сотрудник, имевший к нему доступ: прежний секрет перестаёт действовать сразу.
- Задержка вашей обработки не должна подходить к таймауту: держите 95-й перцентиль заметно ниже 10 секунд.
Подробности по CPA-двери и клиентская проверка подписи в Go — в разделе Go SDK.