Getting Started

Product Catalog



Invoices, Credit Notes and Quotes



Site Configuration

Data Privacy & Security

Data Operations

Reports and Analytics


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 not recommended for time-critical applications. It is very much possible and even likely that webhooks reach your application out-of-order and that they get duplicated. For time-critical applications, we recommend using the list events API  to poll our system for events.

Configure Webhooks 

To configure your webhooks, go to Settings > Configure Chargebee > API Keys and Webhooks. Then switch to the Webhooks tab.

If you haven't added a webhook already, click Add Webhook. You can create up to five webhooks.

Webhook Name and URL 

The webhook name is the name by which the webhook will be referred to in Chargebee. The URL is the one at which your application would be listening to the webhook.

Basic Authentication 

It is recommended that your webhook URLs be protected using basic authentication and/or HTTPS.

To use basic authentication, toggle Protect webhook URL with basic authentication and fill in the Username and Password.

Another (less secure) way of authenticating a webhook call is by including a key generated by you, as part of the webhook URL. For example, the URL could look like:

API Version 

Chargebee supports multiple API versions. The event content sent to the webhook is structured based on the API version selected. Hence it is crucial that the API version of the webhook matches the API version of the client library used by your application server. Learn more about API versioning here .

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

Set this as primary 

The statuses of all webhooks for an event are available in the array attribute webhook inside the event resource .

When you define a webhook as primary, its status is supplied in the webhook_status attribute of the events resource. This is to ensure backward compatibility with an earlier API where only one webhook was configurable for a site.

Exclude card information 

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.


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.

Test Webhooks 

You can test a webhook once it is created.

  1. Click on Test Webhook on the card for the webhook.
  2. Choose an event to test with.
  3. Click Test URL. The request sent, the status of the response received and the response itself is displayed.
See also

List of all events  that webhooks are triggered for.

Update or Remove Webhooks 

To change a webhook's configuration or to delete it, click on the More Options menu on the webhook card.

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 retry


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 and open the page for the chosen event. On the right side, you will have the option to select the webhook and resend the same.

Duplicate Handling 

Due to webhook retries, it's possible that your application receives the same webhook more than once. Ensure idempotency of the webhook call by detecting such duplicates within your application. This can be done by examining the id parameter since its value is unique to an event and thus identifies it.

Out-of-Order Delivery 

Webhooks can also arrive at your application out-of-order. This can be due to issues such as network delays or webhook failures. However, you can determine the order of the events by examining the resource_version attribute of the resource sent by the webhook. resource_version is incremented once for every change made to the resource.

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.

Was this article helpful?