Биллинговые вебхуки

Когда биллинговый вендор (например, Stripe) сообщает платформе о том, что что-то произошло — платёж прошёл, подписка продлилась, платёж оспорен — это входящее событие записывается по каждому проекту до его обработки. Семейство /platform/v1/billing/webhooks позволяет увидеть, что именно пришло, успешно ли прошла обработка, и повторно запустить всё, что не удалось.

Просмотр событий

curl https://api.fvpn.net/platform/v1/billing/webhooks \
  -H "Authorization: Bearer $FVPN_API_KEY" \
  -H "X-Project-Id: $FVPN_PROJECT_ID"

GET /platform/v1/billing/webhooks перечисляет недавние события; GET /platform/v1/billing/webhooks/search фильтрует их. Каждая запись о событии несёт:

• event_type — имя события у вендора
• status и processing_attempts — где событие находится в своём жизненном цикле
• received_at / processed_at — временная линия от приёма до завершения
• last_error — сообщение об ошибке, когда обработка не удалась
• raw_payload_b64 и decoded_summary — доказательства, дословно

Состояние и задержка

Две модели чтения показывают, справляется ли обработка вебхуков:

• GET /platform/v1/billing/webhooks/health — снимок текущего состояния конвейера;
• GET /platform/v1/billing/webhooks/lag-timeseries — задержка от приёма до обработки во времени; именно этот показатель стоит выводить в оповещения.

Повтор

Обработка идемпотентна, поэтому неудавшееся (или подозрительное) событие можно безопасно запустить повторно:

curl -X POST https://api.fvpn.net/platform/v1/billing/webhooks/$EVENT_ID/replay \
  -H "Authorization: Bearer $FVPN_API_KEY" \
  -H "X-Project-Id: $FVPN_PROJECT_ID"

Повтор — это инструмент восстановления при инцидентах вендора: найдите неудавшийся отрезок с помощью search, повторите события и наблюдайте, как health возвращается в зелёный.

Справочник

Полные формы запросов и ответов — в сгенерированном справочнике API в разделе platform-billing. Само состояние биллинга (тарифы, подписки, счета) находится в более широком семействе /platform/v1/billing/*, документированном рядом.