Events

Introduction

Whenever any important changes happen in your Chargebee site, they are recorded as events. An event contains data about affected resources and additional details such as when the change occurred. For example, when a subscription is cancelled due to non payment, an event subscription_cancelled is recorded.

Webhooks

If webhooks have been configured in Chargebee, events trigger those webhooks. If multiple webhooks have been configured, for every event, each webhook is called one after another. If a webhook call for an event fails or times out, it is retried based on a fixed schedule. The webhook call is an HTTP POST with content type application/json.

Caution: 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 Chargebee for events.

Retries & Duplicate Handling

To mark a webhook notification successful, we expect the HTTP status code to be 2XX from your webhook URL. If we don't receive 2XX response code, we retry calling your webhook with a progressively increasing delay for the next 2 days. You could also resend webhooks manually from the web console. 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 uniquely identifies an event. For example, your application could do the following for each webhook notification:

Get the event id and keep it in a persistent store such as a relational database or redis.
Check whether the event id is already processed.
If the event has not been processed then process the event; otherwise, it is a duplicate event so can be ignored.
Also, since the last retry for a webhook happens at around 3 days and 7 hours after the original event trigger, keep the idempotency window as 3 days and 7 hours. In other words, you may purge the stored event ids that are more than 3 days and 7 hours old.

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 order the events by examining the resource_version attribute of the resource sent by the webhook. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds. For example, if you wish to sync resource changes from Chargebee to your application, you could:

Get the value (rv1) of the resource_version attribute from the resource in the webhook.
Get the value (rv2) of resource_version from the resource stored on your side.
If rv1 > rv2, process the resource; otherwise, ignore.

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 that 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 > Configure Chargebee > Webhooks),choose the tab for the webhook and check the option My webhook URL is protected by basic authentication.
Enter Username and Password and click Update Webhook. 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 ensure the integrity of the event data by fetching it again using the Retrieve an Event API call.

Webhook IP Addresses

Webhooks from Chargebee originate from a specific set of IP addresses.

Sample EventJSON

API Index URL

https://[site].chargebee.com/api/v2/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

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.

origin_user

optional, string

The email address of the user, if captured, in the API operation that triggered the event. This email address is captured through either the chargebee-request-origin-user or chargebee-request-origin-user-encoded custom HTTP request headers.

Note: Applicable only when event_source is api.

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.