Webhooksv1

Webhooks

Create webhooks inside ecom9 to receive billing events in real time. If you would rather react to a single event than poll the status endpoints, webhooks keep your product in sync with less overhead.

Overview

Each webhook event delivers simplified data so you can build on top of ecom9 without handling Stripe object relationships. We normalize and link everything behind the scenes, then send you the fields that matter for access control and workflows.

Key idea

Every event includes the original account_ref_id so you can map the webhook to a customer, org, or workspace in your own system.

Events

The events below are the only ones you need to build reliable billing automation. Each event includes the related account_ref_id.

If you need additional confirmation, you can call the Account Status endpoint after receiving a webhook.

`invoice-paid`

Payment completed for a one-time invoice or manual invoice.

{
  "success": true,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "invoice.paid",
  "invoice_id": "in_1abc123def456",
  "amount": 29.99,
  "credit_amount": 0,
  "tier_credit_amount": 0,
  "email": "client@example.com",
  "account_ref_id": "usr_abc123"
}

`subscription-created`

A new subscription was started.

{
  "event": "subscription-created",
  "account_ref_id": "ACC123456789",
  "product_manage_id": "P6ZmR29aTyQb",
  "subscription_id": "sub_xxxx",
  "label_name": "pro",
  "is_active": true,
  "timestamp": "2024-01-15T10:35:00Z"
}

`subscription-deleted`

A subscription was canceled or ended.

{
  "event": "subscription-deleted",
  "account_ref_id": "ACC123456789",
  "product_manage_id": "P6ZmR29aTyQb",
  "subscription_id": "sub_xxxx",
  "label_name": "pro",
  "is_active": false,
  "timestamp": "2024-01-15T10:35:00Z"
}

`subscription-paused`

Access should be paused until resumed.

{
  "event": "subscription-paused",
  "account_ref_id": "ACC123456789",
  "product_manage_id": "P6ZmR29aTyQb",
  "subscription_id": "sub_xxxx",
  "label_name": "pro",
  "is_active": false,
  "timestamp": "2024-01-15T10:35:00Z"
}

`subscription-resumed`

Access should be restored.

{
  "event": "subscription-resumed",
  "account_ref_id": "ACC123456789",
  "product_manage_id": "P6ZmR29aTyQb",
  "subscription_id": "sub_xxxx",
  "label_name": "pro",
  "is_active": true,
  "timestamp": "2024-01-15T10:35:00Z"
}

# Your webhook endpoint should respond with 200 OK after processing
HTTP/1.1 200 OK
Content-Type: application/json

{"received": true}

Product Selection

When you create a webhook in ecom9, you select which product it should listen to. This keeps events scoped and makes filtering unnecessary on your side.

Subscription products

Subscription products emit the subscription lifecycle events listed above: subscription-created, subscription-deleted, subscription-paused, and subscription-resumed.

Single products

Single products (credits, one-time items, or services) emit invoice-paid when payment completes. This is the best signal to confirm a transaction finished, including manual invoices that you send through ecom9 or a CRM.

Integration Notes

Respond with 200 OK quickly after processing to acknowledge the event.
Use idempotent handlers so retries do not double-apply changes.
Store the latest event timestamp if you need to reconcile access over time.

Support

Need a new event or payload tweak? Reach the team through your dashboard chat or email support, and we'll scope it with you.