Enable webhooks

Enable webhooks to create a tight integration with your app.

Bunny can send webhooks when various events happen during a customer or subscription lifecycle. For example, when a new subscription is created or cancelled or perhaps when a payment failed.

Out of the box webhooks

Bunny includes the following webhooks to help with enabling self-service or product-led saas applications using the Bunny customer portal.

• Tenant provisioning change - This is sends the current subscription state and features that should be enabled on a tenant. It will be sent on creation, cancellation and any other change that happens to the subscription.

• Checkout validation - This hook is useful if you want to validate that a user can change plan before allowing it via the Bunny customer portal.

Custom webhooks

Webhooks in Bunny are sent via Bunny Workflows which means that they can be customized and configured to get the data you need in the format you want.

To setup a new custom webhook go to Other > Workflows, create a new workflow, select the model and condition that you want to trigger the webhook using and then select the webhook action.

You can customize the json payload or if the payload is blank we will send the default payload for the model type that was selected as a condition.

Setup a webhook endpoint

Webhook endpoints are configured in the Platforms section of Bunny you'll find this under the Other > Platforms menu.

• Set the url of your applications webhook recieving endpoint.

• Click the Test webhook action to send a sample webhook request to your endpoint.

Enable provisioning

If you are developing locally and want to test your webhook endpoint we suggest using Ngrok to expose your endpoint to the internet. Alternatively you could use a free service like RequestBin to setup a temporary webhook endpoint.

Enhance the security of your webhook endpoint

To prevent malicious actors sending fake payloads to your webhook endpoint we recommend using the following settings to improve security by making it possible to verify that Bunny was the sender of the webhook.

• Webhook auth token - You can create your own token/apikey and set it in Bunny. This value will be included as bearer token in an "Authorization" header of the webhook request.

• Webhook signing key - We will use this value as the shared secret key to generate a HMAC-SHA1 hash of the webhook request body. The resulting signature will be include in the x-bunny-signature header so you can use it to verify that the payload was sent by Bunny. Learn more about verifying the signature.

Verify the webhook signature

If want to improve the security of the webhook and prevent malicious actors sending fake payloads to your endpoint then we recommend that you verify the webhook signature.

To do this you need to set a webhook signing key when configuring the webhook in Bunny. Bunny will use this secret to sign the webhook payload and then include the signature in a x-bunny-signature header.

You will extract the signature from the webhook header and then compare it against your own HMAC-SHA1 hash of the payload using your signing key.

To make signature validation easier you can use one of our SDKs.

Ruby

signature = request.headers["x-bunny-signature"];

payload = '{"type":"SubscriptionProvisioningChange","payload":{"subscription":{"id":27,"state":"trial","trial_start_date":"2022-06-04","trial_end_date":"2022-06-18","start_date":null,"end_date":null,"auto_renew":false,"account":{"id":33,"name":"Ondricka, Flatley and Kessler"},"tenant":null,"product":{"code":"stealth","name":"Stealth","description":null,"sku":null},"features":[{"code":"users","quantity":1},{"code":"crm","quantity":null}]}}}'

signingKey = "<signing_key>";

valid = BunnyApp::Webhook.verify(signature, payload, signing_key)

Node.js

let signature = req.headers["x-bunny-signature"];

let payload = '{"type":"SubscriptionProvisioningChange","payload":{"subscription":{"id":27,"state":"trial","trial_start_date":"2022-06-04","trial_end_date":"2022-06-18","start_date":null,"end_date":null,"auto_renew":false,"account":{"id":33,"name":"Ondricka, Flatley and Kessler"},"environment":null,"product":{"code":"stealth","name":"Stealth","description":null,"sku":null},"features":[{"code":"users","quantity":1},{"code":"crm","quantity":null}]}}}';

let signingKey = "<signing_key>";

let valid = bunny.webhooks.validate(signature, payload, signingKey);