How-to integrate your SaaS with Bunny for tenant provisioning
A critical part of delivering a great SaaS customer experience is making sure that customers have access to the features and usage limits that they have subscribed to. Getting it wrong can leave customers with less features than they expected or higher usage limits than they paid for. In either case it can result in low customer satisfaction, missed revenue and churn.
In a previous post we discussed the concept of subscription entitlements which are the features and usage limits that a customer is entitled to under a given pricing plan. In this post we will go into detail about how to set up tenant provisioning in Bunny from a developers perspective.
Primer on Bunny terminology
Before we get started let's quickly discuss some of the objects that you will see throughout this post and your time developing with Bunny.
Platform - A platform is an object in Bunny that represents your SaaS application. Bunny supports managing multiple platforms which is useful after a company does an acquisition but in most cases you will only have a single platform object in Bunny.
Tenant - A tenant object represents a customer's tenant in your SaaS application. Therefore a platform has many tenants.
Account - An account represents one of your customers. Accounts hold billing information and have contacts, deals and tenants.
Products, Plans, & Price Lists - These objects represent the pricing plans that you sell. You don't need to have products set up to test tenant provisioning but if you do want to set up products, we recommend using the Product Quick Start.
Subscription - A subscription is a contract between you and a customer to purchase a plan on a recurring basis. In Bunny a subscription brings together an Account, Tenant and Plan and holds information about how often and how much to bill.
Enable provisioning on the platform
All Bunny instances start out with a platform called Main. You can rename this if you want but for now let's assume we’re enabling provisioning on the Main platform.
First select Products > Platforms from the top menu and then select Main to view and update it.
The minimum configuration is to toggle the Provisioning enabled switch to the on position and enter a webhook url.
Webhook URL - This is a publicly accessible HTTPS endpoint that is part of your SaaS application. Bunny will POST provisioning payload messages to this address that contain information about the features and usage limits to enable. For your initial testing you may like to use a service like https://requestbin.com to catch the request so you can inspect the payload.
Webhook auth token - When supplied, Bunny will include this as a bearer token in an Authorization header on the webhook request. You may use this like an API key to authorize the request as it hits your webhook endpoint.
Webhook signing key - An optional shared secret that is used to generate a signature for the webhook payload. The signature is included in a x-bunny-signature header with the webhook request.
Testing the webhook request
Once you have an endpoint setup and saved on your Platform you can send test requests by clicking the Test webhook action. This method of testing does not require that products, plans, accounts or subscriptions be created and offers a quicker way to validate that the endpoint is working as you expect.
When the webhook is received you can validate the Authorization header, the payload signature and then inspect the payload body for the features and limits that should be activated for a given tenant in your SaaS application.
Inspecting the webhook payload
The test payload has fake products and features, but has the same structure as a payload that you would get from a normal paid subscription. The payload contains the information about the account that the new or updated subscription is for as well as the contact person.
More importantly, it contains information about the subscriptions that have changed. In most cases you will only have a single subscription but Bunny does support the ability for your customers to subscribe to multiple products.
You will also note a features attribute which is a summary of all of the provisionable features for this tenant across all of the subscriptions that are linked to it. These are the features and usage limits that you need to enforce in your SaaS application.
For example, if the Users feature indicated a quantity of 10 then you should enforce that the tenant is limited to having 10 users.
{
"type": "TenantProvisioningChange",
"payload": {
"tenant": {
"id": 144,
"code": "provisioning-test",
"name": "Provisioning Test",
"platform": {
"id": 1,
"code": "main",
"name": "Main"
},
"account": {
"id": 233,
"name": "Provisioning Test",
"contacts": []
}
},
"change": {
"features": [
{
"code": "users",
"name": "Users",
"quantity": 10,
"plan": {
"code": "fake",
"name": "Fake Plan"
},
"price_list": {
"code": "fake",
"name": "Fake Price List"
}
}
],
"subscriptions": [
{
"state": "trial",
"start_date": "2023-01-30",
"end_date": "2024-01-30",
"trial_start_date": "2023-01-30",
"trial_end_date": "2023-02-13",
"plan": {
"code": "fake",
"name": "Fake Plan"
},
"price_list": {
"code": "fake",
"name": "Fake Price List"
},
"features": [
{
"code": "users",
"name": "Users",
"quantity": 10
}
]
}
]
}
}
}Using a Bunny SDK to verify the webhook signature
When a Webhook signing key is saved on your platform, Bunny will perform a SHA1 hash of the payload body and set the resulting value in a x-bunny-signature header.
You can verify this signature by writing your own code to generate a SHA1 hash of the payload using the signing key that you provided or alternately use one of the convenient Bunny SDKs which does this job for you.
For more information on how to use the signing key methods of the SDK see:
Testing with products and subscriptions
Once you’re happy that your endpoint is receiving a test payload from Bunny, it's time to try out a realistic subscription with an account, contact, and price plan.
To get started, you will need to set up a Product and Plan in your Bunny account. The quickest way to do this is using the Product Quick Start which can be found under the Products menu. This will give you an example of the standard small, medium and large plans that most SaaS companies use.
The next step is to create a subscription which can be done via the UI by creating an Account, Contact and Quote then applying the quote. This is how one of you sales people will often create an enterprise deal.
Alternatively, a quicker option for developers is to use a Bunny API client to send the subscriptionCreate mutation. We have convenient helper methods and examples of how to create a subscription using our SDKs.
Or if you are familiar with GraphQL you can read the subscriptionCreate documentation on how to configure this request.
Debugging via the webhook logs
To test your initial implementation you can resend test webhooks as many times as you need via the Test webhook action on the Platform page. However once you move on to testing with real accounts and subscriptions you may want to view the webhook logs.
To find the webhook logs go to the Other > Webhook logs menu.
The webhook logs display all of the requests sent from Bunny to your application including the payload and headers that were set. You can also see the response that Bunny received from your application, which is useful if you’re trying to debug a failing webhook.
You can also use the webhook logs to resend a webhook which is useful if you need to replay a subscription change in production or if you’re just testing and don't want to step through the process of creating new accounts and subscriptions to trigger the request.
Going live
The final step is to go live with your integration. If you’re using the same Bunny tenant for development and live transactions then you wont need to make any changes.
However, if you plan on using a different Bunny account then the main things to remember are:
that your platform has provisioning enabled and a webhook endpoint setup
the product you are subscribing to has its platform field set
As you can see, enabling tenant provisioning is easy to implement and will provide tremendous value to your sales, customer service and finance teams. If you have any questions about how to get started with Bunny, get in touch!
