Skip to content

Webhooks

bc-subscriptions emits outbound webhooks for subscription lifecycle events so your storefront, OMS, or downstream systems can react — fulfil a renewal, sync status, trigger your own email, or update an external ledger. The widgets and the subscriber portal do not require you to consume webhooks; they're for integrating the subscription lifecycle into systems beyond bc-subscriptions.

Register an endpoint

Outbound webhook subscriptions are managed through the admin API:

  • GET /api/v1/admin/webhook-subscriptions — list registered endpoints
  • POST /api/v1/admin/webhook-subscriptions — register an endpoint + the event_types you want delivered
  • GET / PATCH / DELETE /api/v1/admin/webhook-subscriptions/{id} — manage one

See the request/response shapes and the full event_types enum in the Swagger UI (the spec is authoritative — the lifecycle taxonomy is broad and evolves).

Headline lifecycle events

The events most integrations subscribe to:

Event Fires when
subscription.created A subscription is created (e.g. checkout completes)
subscription.activated A subscription becomes active and billable
subscription.charged A scheduled renewal charge is attempted
charge.succeeded A charge settles successfully
charge.failed A charge fails (enters dunning/retry)
subscription.past_due Dunning exhausted retries without recovery
subscription.paused / subscription.resumed A subscriber pauses or resumes
subscription.cancelled A subscription is cancelled

This is the headline set, not the complete list — the spec carries the full enum (skip/swap, gift, prepaid, B2B change-request, shipping, and more).

Payloads and delivery

Each delivery carries the event_type, a timestamp, and the affected entity (subscription / charge). Field shapes are defined in the OpenAPI spec — validate against it rather than hand-modelling the payload. Charges reference BigCommerce vault instrument IDs; raw card data is never present in a payload (ADR-0037).

Testing webhooks

Lifecycle events fire identically in Stripe test mode. Point a registered endpoint at an HTTPS tunnel and run the test-mode walkthrough to watch subscription.charged → charge.succeeded (and a declined card → charge.failed → dunning) arrive during development.