Getting Started

Building Blocks

Custom Fields

Subscription Features




Order Management

Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Revenue Recovery

Hosted Pages


Reports and Analytics

Data Privacy & Security

Fraud Management


Open Source Resources

Other Features

API Integration

Third Party Integrations

Webhook Settings 

Webhooks are a great way of being notified of changes that happen in your billing system. You can configure Chargebee to notify your system via a webhook call and let your application know when the event occurs.


Webhooks are asynchronous and are sent out as soon as the event occurs, but sometimes there may be a delay of a few minutes.

Configuring Webhooks 

To configure your webhooks, go to Settings > Configure Chargebee > Webhooks.

If you haven't added a webhook already, click Add new webhook. You have the option to create up to five webhooks.

Basic Authentication

When you create your webhook, we recommend that you use basic authentication (by adding a username and password) and/or HTTPS for your webhook URL.

To use basic authentication, select the option My webhook URL is protected by basic authentication and fill in the required Username and Password.

You may also randomly generate a key for your website and add it along with your webhook URL. This method is less secure than basic authentication as it will be recorded in your access logs.

API Version

Chargebee supports multiple API versions. Hence, you need to select the API version for your webhook. The event content sent to the webhook is structured based on the API version selected. This version needs to be the same as the API version used by your webhook server's client library. Learn more about API versioning here .

If you use V1 and plan to upgrade to V2, ensure that you transition your webhooks too. Take a look at the Upgradation Guide  for more details.

Advanced Settings

If you have configured more than one webhook, you can mark one of them as the primary webhook by checking the option Set this as primary. You also have the option to exclude card object from the webhook call. Enabling this will remove the masked card details object from the webhook call sent to you. You can enable this option if you do not require masked card details as part of the webhook data:


Although only masked card details are sent as part of the webhook data, we recommend this option be enabled as the data could still be used for phishing attacks in case your site suffers a security breach.

Click Test URL to check if the URL provided is working. The response status is displayed on the page:

The request sent as well as the response received are recorded and displayed:

While testing a webhook call, a request is sent for the event "subscription_created" by default. If you would like to test the webhook calls for any other events such as "invoice_created" or "card_updated", select that particular event from the drop down menu available.

If the test is successful, you can save the URL.


Chargebee sends webhook calls for all events mentioned here .

Webhook Timeouts 

There are 3 timeouts for Webhooks in Chargebee:

  1. Connection Timeout: The connection timeout is the timeout for making the initial connection to the webhook URL's HTTP server.

  2. Read Timeout: Once the initial connection has been made, at any time there is a possibility that there is an indefinite wait to read data from the HTTP server. The read timeout is the timeout for such a wait.

  3. Total Webhook Timeout: In addition to the above timeouts, Chargebee also checks the total execution of time of any webhook call via the webhook execution timeout.

The values for each timeout are as follows:


For Test site

For Live site

Connection Timeout

10,000 ms

20,000 ms

Read Timeout

10,000 ms

20,000 ms

Webhook Execution Timeout

20,000 ms

60,000 ms

Automatic Retries 

Webhook execution can fail due to timeouts or errors. For each event whose webhook call fails, the calls are retried up to 7 times based on the following schedules:




2 minutes after the failure


6 minutes after the previous retry


30 minutes after the previous entry


1 hour after the previous retry


5 hours after the previous retry


1 day after the previous retry


2 days after the previous retry


You could resend a webhook call manually, if you wish to sync your data immediately. Go to LogsEvents › Open the details page for the chosen event. On the right side, you will have the option to select the webhook and resend the same.

Please refer to our Events API  to learn more.

What IP addresses does Chargebee use that I should whitelist? 

We use Amazon's EC2 for our infrastructure and currently we do not have a static IP address assigned. IP addresses for our instances are automatically allocated by Amazon, as we scale up or down. Hence, we are unable to provide any specific IP address for whitelisting.

Removing Webhooks 

To remove a configured webhook, go to Settings > Configure Chargebee > Webhooks. Open the webhook you wish to remove and click the Delete option available on the top right corner.

Was this article helpful?