Welcome to Bundled API
Welcome! This documentation will help you integrate your service with Bundled's platform. When customers purchase bundles that include your service, you'll receive webhook notifications so you can automatically provision access for them.
How It Works
Here's what happens when a customer purchases a bundle that includes your service:
- You register your webhook endpoint with Bundled using this API
- We send webhook events to your endpoint when subscriptions are created, updated, cancelled, refunded, or renewed
- You process the webhook payload and provision (or update) access for the customer on your platform
What You'll Do
- Register your webhook endpoints to receive subscription events
- Handle webhook events to automatically provision customer access
- Test your integration in sandbox before going to production
- Manage your endpoints through our REST API
Quick Start
Ready to get started? Follow our Quick Start Guide to register your first webhook endpoint.
-
Get Your API Key
Contact Bundled to receive your API key. You'll use this to authenticate your requests to our API.
-
Register Your Webhook Endpoint
Use the Register Webhook Endpoint endpoint to tell us where to send webhook notifications. You'll need to register separately for each event type you want to receive.
-
Implement Your Webhook Handler
Build an endpoint that accepts POST requests and handles webhook events. You'll need to handle
subscription.created,subscription.updated,subscription.cancelled,subscription.refunded, andsubscription.renewedevents based on what you registered for. -
Test in Sandbox
Test your integration thoroughly in the sandbox environment before moving to production. Use the "Simulate a webhook event" endpoint to send test events to your webhook URL. This endpoint is only available in sandbox.
Key Features
- ✅ Simple Integration - Register your endpoints with a single API call
- ✅ Reliable Delivery - We automatically retry failed webhook deliveries to ensure you receive all events
- ✅ Sandbox Testing - Test your integration safely before going live with real customers
- ✅ Secure - Credentials encrypted at rest, delivered over HTTPS
- ✅ Idempotent - Each event has a unique ID, so you can safely handle duplicate deliveries
Security
Your webhook credentials are protected at every stage:
| Stage | Protection |
|---|---|
| At rest | Your Basic Auth credentials are encrypted in our database |
| In transit | All webhook deliveries are sent over HTTPS |
| Authentication | We use HTTP Basic Auth to authenticate requests to your endpoint |
Important: Your webhook endpoint URL must use HTTPS. We will not deliver webhooks to HTTP (non-secure) endpoints.
How to Validate Incoming Webhooks
When we send a webhook to your endpoint, we include an Authorization header with the credentials you provided during registration:
Code
Your endpoint should:
- Extract the
Authorizationheader from the incoming request - Decode the base64 value to get
username:password - Verify it matches the credentials you registered with Bundled
- Reject requests with invalid or missing credentials
Most web frameworks have built-in Basic Auth middleware that handles this automatically.
Best Practices
- Use strong, unique passwords for your webhook credentials
- Rotate your credentials periodically by re-registering your endpoint
- Validate the Basic Auth credentials on every incoming webhook request
- Return a
200 OKresponse promptly to acknowledge receipt
Environments
Bundled provides two separate environments for your integration:
| Environment | Purpose | Base URL |
|---|---|---|
| Sandbox | Development and testing | https://api-sandbox.gobundled.com |
| Production | Live customer transactions | https://api.gobundled.com |
The API Reference in this portal uses the sandbox environment, so you can safely test your integration without affecting production data.
Sandbox Environment
The sandbox environment is a complete replica of production, but with no real transactions. Use it to:
- Develop and test your webhook handler
- Simulate different subscription events
- Verify your integration handles all event types correctly
- Test error handling and edge cases
Sandbox and production are completely isolated. Your sandbox API key, webhook endpoints, and test data do not affect production.
Moving to Production
Once you've tested your integration in sandbox, follow these steps to go live:
-
Complete Sandbox Testing
Ensure your integration correctly handles all event types you've registered for:
subscription.created- Provision access for new customerssubscription.updated- Update customer access (e.g., plan changes)subscription.cancelled- Revoke or schedule access removalsubscription.renewed- Confirm continued access
-
Request Production API Key
Contact Bundled to receive your production API key. This is a separate key from your sandbox key.
-
Register Production Webhook Endpoints
Register your production webhook URLs using the production API. You'll need to register each event type separately, just like in sandbox.
Code -
Use Production Credentials
Update your application to use different credentials for each environment:
- Use your production API key for production requests
- Point to your production webhook URL (not sandbox/staging)
- Use strong, unique passwords for production Basic Auth
-
Monitor and Verify
After going live, monitor your webhook endpoint to ensure events are being received and processed correctly. Check your logs for any failed deliveries or errors.
Environment Checklist
Before going to production, verify:
- All event types tested in sandbox
- Production webhook URL is HTTPS
- Production webhook URL is publicly accessible
- Basic Auth credentials are different from sandbox
- Your endpoint returns
200 OKfor successful processing - Your endpoint handles duplicate events (idempotency)
- Error handling and logging are in place
Important Notes
- Separate data: Sandbox and production have completely separate databases. Endpoints registered in sandbox do not exist in production.
- Separate API keys: Your sandbox API key will not work in production, and vice versa.
- Test endpoint is sandbox-only: The "Simulate a webhook event" endpoint is not available in production. Complete all testing in sandbox before moving to production.
Next Steps
- Get Started - Step-by-step integration guide
- API Reference - Complete API documentation
- Webhook Events - Event types and payloads
- Authentication - API keys and security
Need Help?
If you have questions or need assistance, please contact [email protected] or visit our support portal.