Billing webhooks

When a billing vendor (for example Stripe) tells the platform something happened — a payment succeeded, a subscription renewed, a charge was disputed — that inbound event is recorded per project before it is processed. The /platform/v1/billing/webhooks family lets you see exactly what arrived, whether processing succeeded, and re-run anything that failed.

Inspecting events

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 lists recent events; GET /platform/v1/billing/webhooks/search filters them. Each event record carries:

• event_type — the vendor's event name
• status and processing_attempts — where the event is in its lifecycle
• received_at / processed_at — the ingestion-to-completion timeline
• last_error — the failure message, when processing didn't succeed
• raw_payload_b64 and a decoded_summary — the evidence, verbatim

Health and lag

Two read models tell you whether webhook processing is keeping up:

• GET /platform/v1/billing/webhooks/health — a snapshot of the pipeline's current state;
• GET /platform/v1/billing/webhooks/lag-timeseries — ingestion-to-processed lag over time, the number to alert on.

Replay

Processing is idempotent, so a failed (or suspicious) event can be re-run safely:

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"

Replay is the recovery tool for vendor incidents: find the failed window with search, replay the events, watch health return to green.

Reference

Full request/response shapes are in the generated API reference under platform-billing. Billing state itself (plans, subscriptions, invoices) lives in the wider /platform/v1/billing/* family documented alongside it.