> For the complete documentation index, see [llms.txt](https://docs.bunny.com/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bunny.com/developer/webhooks/webhooks.md).
# Webhooks overview
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.
There are 2 ways that webhooks are configured in Bunny
* [**Platform provisioning**](#platform-webhooks) - When provisioning is enabled on a platform Bunny will send webhooks when a subscription state changes. e.g. Trial to paid or an increase in quantities.
* [**Workflows**](#worflow-webhooks) - A webhook action can be used to send default or custom payloads based on workflow conditions.
### Platform 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.
#### Configure a platform webhook
Navigate to the Settings > Platforms section and toggle **Provisioning enabled** to the on position.
### Workflow webhooks
A webhook action can be added to any workflow. By default it will send a JSON payload containing the fields of the object that is the target of the workflow.
*For example, when targeting the Invoice model.*
```json
{
"type": "Invoice",
"payload": {
"id": 71,
"account": {
"id": 72,
"name": "Swift Mobility Solutions"
},
"amount": "2000.0",
"amount_due": "2000.0",
"amount_paid": 0,
"coupon_applied": "coupon_applied",
"credits": "credits",
"currency_id": "USD",
"description": "Invoice #I-70",
"due_at": "2025-10-27",
"invoice_items": [
{
"id": 84,
"amount": "2000.0",
"charge": {
"id": 86,
"price": "200.0",
"price_list_id": 37,
"created_at": "2025-09-27T17:00:01.153-07:00",
"updated_at": "2025-09-27T17:00:01.153-07:00",
"warren_id": 1,
"price_list_charge_id": 72,
"name": "Users",
"quantity": 10,
"discount": "0.0",
"amount": "2000.0",
"subscription_id": 15,
"quantity_min": 1,
"quantity_max": null,
"price_decimals": 2,
"start_date": "2025-09-09",
"end_date": "2025-10-08",
"quote_charge_id": 100,
"proration_rate": "0.0",
"subtotal": "2000.0",
"tax_amount": "0.0",
"trial": false,
"is_ramp": false,
"tax_code": null,
"vat_code": null,
"kind": "renew",
"charge_type": "recurring",
"pricing_model": "volume",
"billing_period": "monthly",
"evergreen": false,
"round_up_interval": null
},
"charge_type": "SubscriptionCharge",
"currency_id": "USD",
"discount": "0.0",
"is_ramp": "is_ramp",
"line_text": "Ultimate - Users",
"position": null,
"price": "200.0",
"price_decimals": 2,
"price_tiers": [
{
"id": 199,
"starts": 1,
"ends": 100,
"price": "200.0",
"subscription_charge_id": 86
},
{
"id": 200,
"starts": 101,
"ends": 500,
"price": "180.0",
"subscription_charge_id": 86
},
{
"id": 201,
"starts": 501,
"ends": null,
"price": "160.0",
"subscription_charge_id": 86
}
],
"proration_rate": "0.0",
"quantity": 10,
"subtotal": "2000.0",
"tax_amount": "0.0",
"tax_code": null,
"vat_code": null
}
],
"is_legacy": false,
"net_payment_days": 30,
"number": "I-70",
"operations": "operations",
"paid_at": null,
"payment_applications": [],
"po_number": null,
"quote": {
"id": 58
},
"small_unit_amount_due": "small_unit_amount_due",
"state": "due",
"subtotal": "2000.0",
"tax_amount": "0.0"
}
}
```
#### Available webhook objects
The following workflow objects can be used to trigger webhooks:
* Account
* Bill Run
* Contact
* Coupon
* Deal
* Email
* Entity
* Event
* Feature Usage
* Feature
* Financial Account
* Invoice
* Job
* Journal Entry Line
* Payment Method
* Payment
* Plan
* Price List Charge
* Price List
* Product
* Quote
* Revenue Movement
* Subscription
* Tenant
* User
{% hint style="warning" %}
To get an sample payload for click the **Send test webhook** link in your workflow action.
{% endhint %}
#### Custom webhook payloads
When configuring a workflow with a webhook action you can customize the JSON payload with templated values based on the workflows target object.
*For example, If the object was a Subscription you could extract the state into a custom payload*
```json
{
"state": "{{subscription.state}}"
}
```
{% hint style="warning" %}
Note that the custom payload must be valid JSON
{% endhint %}
### Set up a webhook endpoint
Webhook endpoints are configured in the Platforms section of Bunny you'll find this under the **Products > 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.
{% hint style="info" %}
If you are developing locally and want to test your webhook endpoint we suggest using [Ngrok](https://ngrok.com) to expose your endpoint to the internet.\
\
Alternatively you could use a free service like [RequestBin](https://public.requestbin.com/r) to setup a temporary webhook endpoint.
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.bunny.com/developer/webhooks/webhooks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.