Webhooks Integration Guide

Overview

Our Webhooks feature lets you receive real-time notifications whenever a sale or subscription event occurs on one of your products.

One-time payments send the new_sale event.
Subscriptions send three possible events:
- new_subscription
- subscription_renewal
- subscription_cancellation

You configure a webhook URL per product, then handle incoming json POST requests in your own backend.

1. Configuring Your Webhook

Open your product’s Advanced Settings
Under Webhooks, click the switch to enable the webhook for that product.
Enter your endpoint (e.g. https://api.yoursite.com/webhooks/orders).
Click Save.

2. Test Webhook Data

When you click Test Webhook, you’ll receive a a static payload (fixed IDs and metadata) with a current timestamp:

{
   "event": "new_sale",
   "timestamp": "2025-05-06T12:06:50.907Z",
   "test": true,
   "product": {
      "id": "prd_5b769147897f4b618d5fbdd9185a0277",
      "name": "Test Product",
      "price": 100,
      "currency": "USD"
   },
   "saleId": "sls_5e8f58314ce44d4db2377ef303a5f85f",
   "subscription": {},
   "customer": {
      "id": "cus_5b769147897f4b618d5fbdd9185a0277",
      "name": "Test Customer",
      "email": "[email protected]",
      "country": "US"
   }
}

Your code should treat test: true payloads the same as live ones, but you can filter on it if you need to.

3. Event Types & Payloads

All webhook bodies share these top-level fields:

Field	Type	Description
`event`	string	One of `new_sale`, `new_subscription`, `subscription_renewal`, `subscription_cancellation`
`timestamp`	ISO 8601	When the event occurred
`test`	boolean	`true` for Test Webhook calls
`product`	object	Details of the product sold/subscribed
`saleId`	string	Unique ID for this sale record
`subscription`	object	Subscription details (empty for one-time)
`customer`	object	Customer details

Below are full example payloads:

3.1 `new_sale`

Fired on each one-time purchase.

{
   "event": "new_sale",
   "timestamp": "2025-05-06T12:06:50.907Z",
   "test": true,
   "product": {
      "id": "prd_5b769147897f4b618d5fbdd9185a0277",
      "name": "Test Product",
      "price": 100,
      "currency": "USD"
   },
   "saleId": "sls_5e8f58314ce44d4db2377ef303a5f85f",
   "subscription": {},
   "customer": {
      "id": "cus_5b769147897f4b618d5fbdd9185a0277",
      "name": "Test Customer",
      "email": "[email protected]",
      "country": "US"
   }
}

3.2 `new_subscription`

Fired when a customer first subscribes.

{
   "event": "new_subscription", 
   "timestamp": "2025-04-30T15:17:40.782Z", 
   "test": true, 
   "product": { 
      "id": "prd_aa3e14e18ad94a108feb26f0939b20fb",
      "name": "Test Subscription", 
      "price": 10,
      "currency": "USD"
   },
   "saleId": "sls_0b77ac990bd04c70b1740be72745220a",
   "subscription": {
      "id": "sub_f86cb415387348b7927ae0d56d9a2efd",
      "interval": "monthly",
      "nextBillingDate": "2025-05-30T15:17:40.782Z", 
      "cancellationDate": ""
   },
   "customer": {
      "id": "cus_5b769147897f4b618d5fbdd9185a0277",
      "name": "Test Customer",
      "email": "[email protected]",
      "country": "US"
   }
}

3.3 `subscription_renewal`

Fired on each auto-renewal charge.

{ 
   "event": "subscription_renewal", 
   "timestamp": "2025-04-30T15:18:06.755Z",
   "test": true, 
   "product": { 
      "id": "prd_aa3e14e18ad94a108feb26f0939b20fb", 
      "name": "Test Subscription", 
      "price": 10, 
      "currency": "USD" 
   }, 
   "saleId": "sls_0b77ac990bd04c70b1740be72745220a", 
   "subscription": { 
      "id": "sub_f86cb415387348b7927ae0d56d9a2efd", 
      "interval": "monthly", 
      "nextBillingDate": "2025-05-30T15:18:06.755Z", 
      "cancellationDate": "" 
   },
   "customer": {
      "id": "cus_5b769147897f4b618d5fbdd9185a0277",
      "name": "Test Customer",
      "email": "[email protected]",
      "country": "US"
   }
}

3.4 `subscription_cancellation`

Fired when a subscriber cancels.

{
   "event": "subscription_cancellation", 
   "timestamp": "2025-04-30T15:18:35.343Z", 
   "test": true, 
   "product": { 
      "id": "prd_aa3e14e18ad94a108feb26f0939b20fb", 
      "name": "Test Subscription", 
      "price": 10,
      "currency": "USD"
   },
   "saleId": "sls_0b77ac990bd04c70b1740be72745220a",
   "subscription": {
      "id": "sub_f86cb415387348b7927ae0d56d9a2efd",
      "interval": "monthly",
      "nextBillingDate": "",
      "cancellationDate": "2025-04-30T15:18:35.344Z" 
   },
   "customer": {
      "id": "cus_5b769147897f4b618d5fbdd9185a0277",
      "name": "Test Customer",
      "email": "[email protected]",
      "country": "US"
   }
}

4. Security

After configuring your webhook URL, you’ll see a Webhook Secret on the Advanced Settings screen.
Signature Header: Each request includes an X-Webhook-Signature header.
Verification: Compute an HMAC SHA-256 using your secret and the raw request body. Compare it against the signature header to validate the payload.

5. Best Practices

Idempotency: Some retries may fire the same event twice—make your handlers safe to run multiple times.
Logging & Monitoring: Capture saleId and subscription.id to correlate with your own records.
Error Handling: If your endpoint returns non-200, we’ll retry several times.