Recca Разработчикам
Меню

Вебхуки

События сети на ваш адрес: конверт, подпись с меткой времени и повторы доставки.

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.approvedCPA-сеть: холд конверсии дозрел, вознаграждение доступно партнёру.external_id, goal, payout_rub, status, partner_external_id, occurred_at
cpa.conversion.declinedCPA-сеть: конверсия отклонена.external_id, goal, payout_rub, status, partner_external_id, occurred_at
cpa.conversion.reversedCPA-сеть: подтверждённая конверсия отменена.external_id, goal, payout_rub, status, partner_external_id, occurred_at
cpa.payout.paidCPA-сеть: оператор отметил выплату выплаченной.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 суток) и повторные пропускайте.

Рекомендации по приёму

  1. Отвечайте быстро (до 10 секунд): проверьте подпись и дубль, верните 2xx, а тяжёлую работу сделайте асинхронно.
  2. Проверяйте подпись до разбора: пока подпись не сошлась, event_type доверия не заслуживает.
  3. Дедуплицируйте по event_id (или X-Recca-Delivery-Id): доставка «минимум один раз», и дубли случаются.
  4. Не отвечайте 5xx на то, что вы не хотите обрабатывать: верните 2xx и отбросьте событие. Ответ 5xx запустит повторы, которые мы не можем отменить.
  5. Смените секрет, когда уходит сотрудник, имевший к нему доступ: прежний секрет перестаёт действовать сразу.
  6. Задержка вашей обработки не должна подходить к таймауту: держите 95-й перцентиль заметно ниже 10 секунд.

Подробности по CPA-двери и клиентская проверка подписи в Go — в разделе Go SDK.