Вебхуки

Входящие вебхуки MeerPartners: зачисление депозита от платёжного провайдера и identity-события MeerID. Формат, HMAC-подпись и идемпотентность по delivery-id.

В MeerPartners есть входящие вебхуки — платформа принимает серверные уведомления от доверенных систем. Все они защищены подписью и идемпотентны.

Исходящих webhook-подписок на события пока нет

На текущий момент платформа не рассылает исходящие вебхуки на события партнёрской программы (конверсия одобрена, выплата проведена и т.п.) — подписаться на них через API нельзя. Если вам нужно знать о состоянии конверсий, опрашивайте данные через кабинет/чтение. Эта страница описывает только входящие вебхуки, которые платформа принимает.

Вебхук зачисления депозита

Когда бизнес пополняет эскроу-баланс, фактическое зачисление происходит не сразу: сначала создаётся pending-намерение (POST /api/v1/merchant/deposit), а деньги зачисляются по серверному вебхуку от платёжного провайдера.

POST/api/v1/merchant/deposit/webhook🔒 HMAC

Это S2S-эндпоинт: его вызывает доверенный провайдер платежей, не браузер. Подпись проверяется до разбора тела.

Подпись

X-Provider-Signature: <hex(HMAC_SHA256(secret, signing_string))>
X-Timestamp: 1717200000

signing_string — та же схема, что у postback:

{METHOD}\n{PATH}\n{X-Timestamp}\n{SHA256_hex(raw_body)}

Секрет — общий секрет вебхука депозита, сконфигурированный оператором (DEPOSIT_WEBHOOK_SECRET). Сверка constant-time.

Тело

{
  "provider": "card",
  "provider_tx_id": "yk_2f9a1c",
  "deposit_intent_id": 88,
  "amount": "5000.00",
  "currency": "RUB",
  "status": "success"
}

Поле	Значение
`provider`	Идентификатор провайдера
`provider_tx_id`	ID транзакции у провайдера — ключ идемпотентности
`deposit_intent_id`	ID намерения, созданного при `POST /api/v1/merchant/deposit`
`amount`	Сумма строкой
`currency`	Валюта, ISO-4217
`status`	`success` / `failed` / `refunded`

Идемпотентность и защита

Дедуп по provider_tx_id: повторная доставка не зачислит депозит дважды.
Анти-replay: X-Timestamp в пределах ±5 минут; повтор той же подписи в окне памяти отклоняется. Окно памяти — в Redis.
Fail-closed: если секрет вебхука не сконфигурирован — запрос отклоняется (503), а не пропускается. Это закрывает дыру недонастроенного окружения на денежном эндпоинте.

Код	HTTP	Когда
`DEPOSIT_WEBHOOK_UNCONFIGURED`	503	Секрет вебхука не задан (fail-closed)
`DEPOSIT_WEBHOOK_SIGNATURE_INVALID`	401	Нет заголовков, неверная подпись, timestamp вне окна или replay
`DEPOSIT_WEBHOOK_REPLAY_STORE_UNAVAILABLE`	503	Хранилище replay-защиты недоступно (fail-closed)
`INVALID_PAYLOAD`	400	Невалидный JSON в теле

Это интеграция оператора с провайдером

Вебхук депозита настраивается на стороне платформы и платёжного провайдера. Бизнесу при обычной работе подключать его самому не нужно — пополнение баланса идёт через кабинет.

Identity-вебхуки MeerID

Поскольку вход — через MeerID, платформа принимает от него identity-события, чтобы вовремя отзывать доступ (бан, удаление аккаунта) и синхронизировать слияния. Это часть SSO-контура и обслуживается порталом — встраивать их в свою интеграцию не требуется.

Back-channel logout

POST/api/v1/auth/meerid/backchannel-logout🔒 —

Приёмник OIDC Back-Channel Logout. Тело — application/x-www-form-urlencoded с полем logout_token. Токен проверяется по JWKS (RS256: iss, aud, exp, наличие события logout, отсутствие nonce). По результату отзываются все сессии пользователя. Неизвестный субъект → no-op 200. Невалидный токен → LOGOUT_TOKEN_INVALID (401).

Identity-вебхук

POST/api/v1/auth/meerid/webhook🔒 HMAC

Принимает события account.merged и account.erased.

HMAC-SHA256 по сырому телу со строкой {timestamp}.{raw_body} и секретом MEERID_WEBHOOK_SECRET (constant-time).
Свежесть |now − ts| ≤ 300 с (анти-replay), иначе WEBHOOK_TIMESTAMP_STALE (401).
Дедуп по заголовку X-MeerID-Delivery (at-least-once безопасно).
event_type берётся только из подписанного тела (заголовки подписью не покрыты).
Неизвестный event_type → 200 no-op (forward-compatible).
Если секрет не задан — fail-closed: любой вебхук отклоняется.

Событие	Действие платформы
`account.merged`	Перепривязка `meerid_sub`; при коллизии — отзыв сессий и деактивация старой записи
`account.erased`	Деактивация, обнуление PII-кэша, отзыв всех сессий пользователя

Подробнее про модель отзыва доступа — в инженерной документации Auth и безопасность.

Идемпотентность вебхуков — общий принцип

Любой входящий вебхук может прийти больше одного раза (повтор при таймауте у отправителя). Платформа гасит дубли по идемпотентному ключу:

Вебхук	Ключ дедупа
Депозит	`provider_tx_id`
MeerID identity	`X-MeerID-Delivery`

Если вы пишете собственную систему-отправитель — присылайте стабильный идентификатор доставки и повторяйте запрос при сбоях: дубликат не навредит.

Что дальше

📡Постбэк (S2S)

Основной серверный канал — отправка конверсий вам.

Открыть

💰Баланс и пополнение

Как устроено пополнение эскроу-баланса со стороны бизнеса.

Открыть

🚦Коды ошибок API

Коды отклонения вебхуков и формат ошибки.

Открыть

НазадSSO / token-exchange ДалееEmbed SDK (виджеты)