Settings
Configure SDK
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 event [ JSON ]
{
"event": {
"api_version": "v1",
"content": {
"customer": {
"account_credits": 0,
"allow_direct_debit": false,
"auto_collection": "on",
"card_status": "no_card",
"created_at": 1517506759,
"excess_payments": 0,
"id": "__test__5SK0bLNFRFuCIi8Nj",
"object": "customer",
"refundable_credits": 0,
"taxability": "taxable"
},
"subscription": {
"created_at": 1517506759,
"due_invoices_count": 0,
"has_scheduled_changes": false,
"id": "__test__5SK0bLNFRFuCIi8Nj",
"object": "subscription",
"plan_id": "plan1",
"plan_quantity": 1,
"started_at": 1517506759,
"status": "in_trial",
"trial_end": 1518802759,
"trial_start": 1517506759
}
},
"event_type": "subscription_created",
"id": "ev___test__5SK0bLNFRFuCIipNm",
"object": "event",
"occurred_at": 1517506759,
"source": "api",
"user": "full_access_key_v1",
"webhook_status": "scheduled"
}
}API Index URL
The types of event provided by chargebee. Refer event types for all the event types provided by us currently.
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.
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.
Event types ¶
This is a list of the event types we currently support. We will continue to add more events moving forward. All events follow a uniform pattern - <resource>_<event_name>. The resources that will be present in the event content are provided beneath each event type's description.
Note: If consolidated invoicing is enabled, the attributes invoice.subscription_id and credit_note.subscription_id should not be used (as it will not be present if the invoice / credit note has lines from multiple subscriptions). Instead to know the related subscriptions, their line_items' subscription_id attribute should be referred.
List events ¶
Retrieves list of events.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing event
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Retrieve an event ¶
Retrieves a specific event identified by a unique event identifier.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing event