Events

Whenever any important changes happen in your Chargebee site, they are recorded as Events. Event contains data about affected resources and additional details such as when it occurred.

You could listen to the events in your application by configuring Webhook url and handle it based on the type of event. We post the event data as request body with content type set as application/json to your webhook url.

For example, when a subscription is cancelled due to non payment, an event "subscription_cancelled" is recorded and fired to your webhook url.

To mark a webhook notification successful, we expect the HTTP status code to be 200 from your webhook url. If we don't receive 200 response code, we retry calling your webhook with exponential time interval for next 2 days. You could also try resending it from our admin console.

API Version: Chargebee supports multiple API versions now. The api_version attribute indicates the API version based on which the event content is structured. While processing webhooks, ensure the api_version is same as the API version used by your webhook server's client library.

Securing your Webhook URL:

You can have basic authentication for the webhook url.

In the Webhook Settings page (Settings > Webhooks), check the option My webhook URL is protected by basic authentication.
Enter Username and Password and click Update Webhook URL OR Generate a random key and have it as part of your webhook url eg. http://yourapp.com/chargebee-webhook/cuktqaem0i2fkd5jt9cdtojcn9cvb3Y

In addition to securing your webhook, you can always fetch the event from Chargebee using Retrieve an Event API call.

Ensure that you keep the secrets secret :)

Sample EventJSON

API Index URL

https://[site].chargebee.com/api/v1/events

Events attributes

required, string, max chars=40

Uniquely identifies a event

occurred_at

required, timestamp(UTC) in seconds

Timestamp indicating when this event had occurred.

source

required, enumerated string, default=none

Source of the event

admin_console

Operation made through the Chargebee admin UI

api

Operation made through the API

scheduled_job

Operation made through the Scheduled Jobs

hosted_page

Operation made through the Hosted Pages

portal

Operation made through Self-Serve Portal

system

Operation that are triggered by ChargeBee System

none

If no source can be identified for an operation

js_api

Operation made through the JS API

migration

Deprecated

bulk_operation

Operation that are triggerd through bulk operation.

user

optional, string, max chars=150

event_type

optional, enumerated string

The types of event provided by chargebee. Refer event types for all the event types provided by us currently.

api_version

optional, enumerated string, default=v1

The Chargebee API Version used for rendering this event content. While processing webhooks, ensure this version is same as the API version used by your webhook server's client library.

Chargebee API version V1

Chargebee API version V2

content

required, jsonobject

The JSON data associated with this event. Has resources (subscription , invoice etc) based on the event type. These resources are structured based on the Chargebee API version indicated by the api_version attribute.

webhooks

Array of webhook call statuses: one for each of the webhooks configured for the site. This object is only available after the first webhook call for the event has completed or timed out. Also, creation/updation of the webhook object data is a queued operation and hence there can be an additional delay of up to 5 seconds.