Webhooks

Restore Hub receives webhooks from billing providers — it does not currently emit outbound webhooks to your server. This page explains the inbound flow so you understand how subscription state is kept in sync.

Stripe — POST /api/billing/webhook

Stripe sends every billing event for Restore Hub customers (subscriptions, invoice payment success/failure, customer updates) to this endpoint. The handler verifies the signature against STRIPE_WEBHOOK_SECRET and updates the user's plan, billing state, and entitlements in the database.

Events we react to:

• checkout.session.completed — new subscription, attach to user
• customer.subscription.updated — plan change, mid-cycle upgrade/downgrade
• customer.subscription.deleted — cancellation, revert to FREE plan
• invoice.payment_succeeded — extend access for next period
• invoice.payment_failed — flag account, send email, eventual downgrade
• charge.refunded — credit ledger and update audit trail

Verification: every request must carry a valid Stripe-Signature header. Unverified requests get 400.

# Stripe sends:
POST https://api.restorehub.net/api/billing/webhook
Stripe-Signature: t=1714000000,v1=...,v0=...
Content-Type: application/json

# We verify with stripe.webhooks.constructEvent(rawBody, sig, secret).
# Reject = 400. Accept = process and 200.

OxaPay — POST /api/oxapay/webhook

OxaPay handles cryptocurrency payments. The endpoint verifies the request hash against the merchant secret, then activates a subscription or extends a plan based on the invoice status.

States we handle:

• Paid — confirmed crypto payment, activate plan
• Confirming — txn submitted, no action yet
• Expired / Failed — clean up the pending invoice record

# OxaPay sends:
POST https://api.restorehub.net/api/oxapay/webhook
HMAC: <hex digest of body using merchant secret>
Content-Type: application/json

# We re-compute the HMAC server-side and compare timing-safely.

Security model

Both endpoints are public but protected by:

• Cryptographic signature verification on every request
• Idempotency: replaying the same event has no additional effect
• Rate limiting at the load balancer
• Audit-log entries on every state change

Outbound webhooks (roadmap)

Outbound webhooks — Restore Hub calling your server when something happens (member verified, backup completed, etc.) — are on the roadmap. For now, poll the API or use the MCP server from inside an agent loop.