ChargebeeAPI

Events

Introduction

When important changes occur on your Chargebee site, they are recorded as events. An event contains data about the affected resources and metadata, such as the timestamp of the change. For example, when a subscription is canceled due to non-payment, an event such as subscription_cancelled is recorded.

Webhooks

If webhooks are configured in Chargebee, events trigger those webhooks. If multiple webhooks are configured, Chargebee calls each webhook sequentially for every event. If a webhook call fails or times out, it is retried based on a fixed schedule. The webhook call is an HTTP POST with the content type application/json.

Caution: Webhooks are asynchronous and are not recommended for time-critical applications. Webhooks may arrive out of order or be delivered multiple times. For time-sensitive use cases, use the List events API to poll Chargebee for events.

Retries and Duplicate Handling

To mark a webhook notification successful, the webhook must return an HTTP status code in the 2XX range. If a 2XX response is not received, Chargebee retries the webhook call with increasing delays for up to 2 days. You can also resend webhook calls manually from the web console. Due to webhook retries, it is possible that your application receives the same webhook more than once. Detect such duplicates within your application to ensure the idempotency of the webhook call. This can be done by examining the id parameter since its value uniquely identifies an event. For example, your application can do the following for each webhook notification:

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

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 can:

  1. Get the value rv1 of the resource_version attribute from the resource in the webhook.
  2. Get the value rv2 of resource_version from the resource stored on your side.
  3. 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 the 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.

  1. On the Webhook Settings page (Settings > Configure Chargebee > Webhooks), select the webhook tab and check the option My webhook URL is protected by basic authentication.
  2. 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.

About Webhook IP Addresses

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

Sample EventJSON

Events attributes

id
required, string, max chars=40

Unique identifier of an event.

occurred_at
required, timestamp(UTC) in seconds

Timestamp indicating when this event had occurred.

source
required, enumerated string, default=none

Indicates the origin of the operation that triggered the event.

Possible Enum Values
admin_console

The event was triggered by an operation performed through the Chargebee Billing dashboard .

api

The event was triggered by an operation performed through the public API .

scheduled_job

The event was triggered by a scheduled job in Chargebee Billing.

hosted_page

The event was triggered by an operation performed by the customer through one of the Chargebee Hosted Pages .

portal

The event was triggered by an operation performed by a customer through the Self-Serve Portal .

user
optional, string, max chars=150
event_type
optional, enumerated string

The type of event provided by Chargebee. See event types for a complete list.

api_version
optional, enumerated string, default=v1

The Chargebee API version used to render this event content. When processing webhooks, ensure that this version matches the one used by your webhook server's client library.

Possible Enum Values
v1

Chargebee API version V1

v2

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
optional, list of webhook

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.