IOSOR

IOSOR База знаний

Контракт webhook до первой отправки

Путь покупателя: согласовать signed URL, типы событий и idempotency key до первого prepaid send — сначала контракт, потом платный трафик.

Prepaid send без контракта webhook — это spend без общей правды. Покупатель должен зафиксировать signed URL, список событий и idempotency key до того, как первое платное сообщение спишет кошелёк — не после вопроса finance, почему status и ledger расходятся. Эта страница — buyer path, не чеклист ключей на запуске и не deep-dive подписи.

Связанные: вебхуки и ключи на запуске, вебхуки, которые переживают запуск, prepaid-резерв до первого списания, Day-1 runway: что должно быть зелёным.

IOSOR — white-label prepaid.

Согласуйте контракт до первого платного send

Платный send значит: кошелёк может списать. Контракт значит: product, finance и ops уже делят, куда приходят callback, какие события — money/status truth, какой ключ делает retry безопасным. Launch habits и runway могут выглядеть зелёными, пока контракт — тред в Slack: это не ready. См.

Signed URL и ownership consumer

Поле контракта Зачем покупателю
HTTPS callback URL Один destination, который называют product и ops
Owner signing secret Кто ротирует; никогда paste в общий чат
Правило ACK vs process Persist сначала; side effects после ACK
Split сред Pilot URL ≠ production URL
Fail closed на unknown host Поддельный delivered не двигает ledger

Типы событий, которые делят product и finance

Перечислите события, которые могут двигать деньги или статус, до первого send: accepted, delivered, failed, expired, inbound STOP и любой verify-результат, который вы примете за truth. Неперечисленные события fails closed — они не изобретают строки ledger. Словарь: Общий язык статусов для product и finance.

Idempotency key до spend

Согласуйте форму ключа до spend: platform event или message ID, сохраняется до side effects, читается рядом со строкой debit. Ключ из timestamp плюс body — путь к double-charge на retry. Soft volume language blocked, пока duplicate-event smoke не покажет одну строку ledger.

Чеклист покупателя по контракту webhook

  1. Signed production URL назван и имеет owner до первого платного send?
  2. Список событий product и finance записан — не устно?
  3. Форма idempotency key согласована и пишется до side effects?
  4. Pilot и production consumers разделены с разными секретами?
  5. Unknown/unsigned callback fails closed с честным status?
  6. Разговор soft USD 1 000/мес blocked, пока контракт в draft?

Начните с IOSOR

Зафиксируйте продуктовый URL вебхука и секрет подписи в консоли IOSOR до первого платного отправления. Настройте обработчик так, чтобы он сначала сохранял входящее событие и отдавал ACK, а уже затем запускал логику обработки. Проведите тест с дублированием ключа идемпотентности, чтобы убедиться, что повторные вызовы не создают фантомных записей в финансовом реестре.

Итог IOSOR

Надежный контракт вебхуков формируется до того, как баланс начинает расходоваться. Согласование единого списка событий между продуктом и финансами, использование явных идентификаторов сообщений вместо генерации ключей из времени, а также четкое разделение среды пилота и продакшена исключают потерю статусов и повторные списания.

Был ли материал полезен?

Связанные гайды