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 ]

{ "id": "ev_8asn8QLqqQqA8", "occurred_at": 1412101820, "source": "system", "object": "event", "api_version": "v2", "content": { "customer": { "id": "8avVGOkx8U1MX", "first_name": "Benjamin", "last_name": "Ross", "email": "Benjamin@test.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1412101813, "taxability": "taxable", "updated_at": 1412101820, "resource_version": 1412101820000, "deleted": false, "object": "customer", "card_status": "valid", "primary_payment_source_id": "pm_8asn8QLqqPW96", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "tok_8asn8QLqqPPf5", "gateway": "chargebee", "gateway_account_id": "gw_8asn8QLqqJps2", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "preferred_currency_code": "USD" }, "card": { "status": "valid", "gateway": "chargebee", "gateway_account_id": "gw_8asn8QLqqJps2", "iin": "411111", "last4": "1111", "card_type": "visa", "funding_type": "credit", "expiry_month": 1, "expiry_year": 2022, "object": "card", "masked_number": "************1111", "customer_id": "8avVGOkx8U1MX", "payment_source_id": "pm_8asn8QLqqPW96" } }, "event_type": "customer_created", "webhook_status": "not_configured" }

API Index URL GET

https://{site}.chargebee.com/api/v2/events
id
Uniquely identifies a event.
string, max chars=40
occurred_at
Timestamp indicating when this event had occurred.
timestamp(UTC) in seconds
source
Source of the event.
enumerated string, default=none
Possible values are
admin_consoleOperation made through the Admin Console.apiOperation made through the API.scheduled_jobOperation made through the Scheduled Jobs.hosted_pageOperation made through the Hosted Pages.
portalOperation made through portal.systemOperation that are triggered by ChargeBee System.noneIf no source can be identified for an operation.js_apiOperation made through the JS API.migrationOperation that are triggered during import.bulk_operationOperation that are triggerd through bulk operation.external_serviceOperation that are triggered via webhook.
Show all values[+]
user
Event created by the user. In case of API, it is API name.
optional, string, max chars=150
event_type
The types of event provided by chargebee. Refer event types for all the event types provided by us currently.
optional, enumerated string
api_version
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.
optional, enumerated string, default=v1
Possible values are
v1Chargebee API version V1.v2Chargebee API version V2.
content
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.
jsonobject
List of webhooks.
optional, list of webhook
Webhook attributes
id
Uniquely identifies a webhook.
string, max chars=40
webhook_status
The current status of the webhook for this event.
enumerated string
Possible values are
not_configuredWebhook was not configured when this event occurred.scheduledWebhook call has been scheduled.succeededWebhook call was successful.re_scheduledWebhook call has been rescheduled due failure(s) in previous call(s).failedWebhook call has been suspended after the all retries have resulted in failure.skippedSkipped as specified in request.not_applicableWebhook call is not applicable for this event.

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.

plan_created
Triggered when a plan is created
plan
plan_updated
Triggered when a plan is changed
plan
plan_deleted
Triggered when a plan is deleted
plan
addon_created
Triggered when an addon is created
addon
addon_updated
Triggered when an addon is changed
addon
addon_deleted
Triggered when an addon is deleted
addon
coupon_created
Triggered when a coupon is created
coupon
coupon_updated
Triggered when a coupon is changed
coupon
coupon_deleted
Triggered when a coupon is deleted
coupon
customer_created
Triggered when a customer is created.
customer,card(optional)
customer_changed
Triggered when a customer is changed
customer,card(optional)
customer_deleted
Triggered when a customer is deleted.
customer,card(optional),subscriptions(optional)
customer_moved_out
Triggered when a customer is copied to another site.
customer,card(optional)
customer_moved_in
Triggered when a customer is copied from another site.
customer,card(optional)
subscription_created
Triggered when a new subscription is created.
subscription,customer,card(optional),invoice(optional),unbilled_charges(optional)
subscription_started
Triggered when a 'future' subscription gets started
subscription,customer,card(optional),invoice(optional)
subscription_trial_end_reminder
Triggered 6 days prior to the trial period's end date.
subscription,customer,card(optional)
subscription_activated
Triggered after the subscription has been moved from "Trial" to "Active" state
subscription,customer,card(optional),invoice(optional)
subscription_changed
Triggered when the subscription's recurring items are changed
subscription,customer,card(optional),invoice(optional),credit_notes(optional),unbilled_charges(optional)
subscription_cancellation_scheduled
Triggered when subscription is scheduled to cancel at end of current term
subscription,customer,card(optional)
subscription_cancellation_reminder
Triggered 6 days prior to the scheduled cancellation date.
subscription,customer,card(optional)
subscription_cancelled
Triggered when the subscription is cancelled. If it is cancelled due to non payment or because the card details are not present, the subscription will have the possible reason as 'cancel_reason'.
subscription,customer,card(optional)
subscription_reactivated
Triggered when the subscription is moved from cancelled state to "Active" or "Trial" state
subscription,customer,card(optional),invoice(optional),unbilled_charges(optional)
subscription_renewed
Triggered when the subscription is renewed from the current term.
subscription,customer,card(optional),invoice(optional),unbilled_charges(optional)
subscription_scheduled_cancellation_removed
Triggered when scheduled cancellation is removed for the subscription.
subscription,customer,card(optional)
subscription_shipping_address_updated
Triggered when shipping address is added or updated for a subscription.
subscription,customer,card(optional)
subscription_deleted
Triggered when a subscription is deleted.
subscription,customer,card(optional)
pending_invoice_created
Event triggered (in the case of metered billing) when a "Pending" invoice is created that has usage related charges or line items to be added, before being closed. This is triggered only when the “Notify for Pending Invoices” option is enabled.
invoice
invoice_generated
Event triggered when a new invoice is generated. In case of metered billing, this event is triggered when a "Pending" invoice is closed.
invoice
invoice_updated
Triggered when the invoice’s shipping/billing address is updated, if the invoice is voided, or when the amount due is modified due to payments applied/removed.
invoice
invoice_deleted
Event triggered when an invoice is deleted.
invoice
credit_note_created
Triggered when a credit note is created
credit_note
credit_note_updated
Triggered when a credit note is updated
credit_note
credit_note_deleted
Triggered when a credit note is deleted
credit_note
subscription_renewal_reminder
Triggered 3 days before each subscription's renewal.
subscription,customer,card(optional)
transaction_created
Triggered when a transaction is recorded
transaction
transaction_updated
Triggered when a transaction is updated. E.g. When a transaction is removed, or when an excess payment is applied on an invoice.
transaction
transaction_deleted
Triggered when a transaction is deleted.
transaction
payment_succeeded
Triggered when the payment is successfully collected
subscription,customer,card(optional),transaction,invoice
payment_failed
Triggered when attempt to charge customer's credit card fails
subscription,customer,card(optional),transaction,invoice
payment_refunded
Triggered when a payment refund is made
subscription,customer,card(optional),transaction,invoice,credit_note(optional)
payment_initiated
Triggered when a payment is initiated via direct debit
subscription,customer,card(optional),transaction,invoice
refund_initiated
Triggered when a refund is initiated via direct debit
subscription,customer,card(optional),transaction,invoice,credit_note(optional)
card_added
Triggered when a card is added for a customer.
customer,card(optional)
card_updated
Triggered when the card is updated for a customer.
customer,card(optional)
card_expiry_reminder
Triggered when the customer's credit card is expiring soon. Triggered 30 days before the expiry date.
customer,card(optional)
card_expired
Triggered when the card for a customer has expired
customer,card(optional)
card_deleted
Triggered when a card is deleted for a customer
customer,card(optional)
payment_source_added
Triggered when a payment source is added.
customer,payment_source
payment_source_updated
Triggered when the payment source is updated and also when a role is assigned to it.
customer,payment_source
payment_source_deleted
Triggered when a payment source is deleted
customer

Retrieves list of events.


NOTE : Only events that are less than null days old will be retrieved
.
Sample Request
curl  https://{site}.chargebee.com/api/v2/events \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode start_time="1349029800" \
     --data-urlencode end_time="1349116200" \
     --data-urlencode id[is_not]="8ndk0hbKm" \
     --data-urlencode source[is_not]="hosted_page" \
     --data-urlencode sort_by[asc]="occurred_at"
copy
curl  https://{site}.chargebee.com/api/v2/events \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode start_time="1349029800" \
     --data-urlencode end_time="1349116200" \
     --data-urlencode id[is]="8ndk0hbKm" \
     --data-urlencode source[is]="hosted_page" \
     --data-urlencode sort_by[asc]="occurred_at"

Sample Response [ JSON ]

{ "list": [ {"event": { "id": "ev_8asyvQLqr6GX1n", "occurred_at": 1496825939, "source": "api", "user": "full_access_key_v1", "object": "event", "api_version": "v2", "content": { "subscription": { "id": "addams", "customer_id": "addams", "plan_id": "no_trial", "plan_quantity": 1, "plan_unit_price": 1000, "billing_period": 1, "billing_period_unit": "month", "plan_free_quantity": 0, "status": "active", "current_term_start": 1496825939, "current_term_end": 1499417939, "next_billing_at": 1499417939, "created_at": 1496825939, "started_at": 1496825939, "activated_at": 1496825939, "updated_at": 1496825939, "has_scheduled_changes": false, "resource_version": 1496825939000, "deleted": false, "object": "subscription", "currency_code": "USD", "due_invoices_count": 0, "mrr": 0 }, "customer": { "id": "addams", "first_name": "Wednesday", "last_name": "Addams", "auto_collection": "off", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1496825939, "taxability": "taxable", "updated_at": 1496825939, "resource_version": 1496825939000, "deleted": false, "object": "customer", "card_status": "no_card", "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "preferred_currency_code": "USD" }, "unbilled_charges": [ { "id": "li_8asyvQLqr6Ei1l", "customer_id": "addams", "subscription_id": "addams", "date_from": 1496825939, "date_to": 1499417939, "unit_amount": 1000, "quantity": 1, "amount": 1000, "discount_amount": 0, "description": "No Trial", "entity_id": "no_trial", "is_voided": false, "object": "unbilled_charge", "entity_type": "plan", "currency_code": "USD" }, {..} ] }, "event_type": "subscription_created", "webhook_status": "scheduled" }}, {..} ], "next_offset": "[\"1496825939000\",\"277000000849\"]" }

URL Format GET

https://{site}.chargebee.com/api/v2/events
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
sort_by[<sort-order>]
Sorts based on the specified attribute.
Supported attributes : occurred_at
Supported sort-orders : asc, desc

Example sort_by[asc] = "occurred_at"
This will sort the result based on the 'occurred_at' attribute in ascending(earliest first) order.
optional, string filter
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
To filter based on Event Id.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "8ndk0hbKm"
optional, string filter
webhook_status[<operator>]
Returns the events (occurred in the past 6 days) which has this status in any of the events' webhooks.
Note : To retrieve events which have occurred before the 6 day period, use the occurred_at(start_time/end_time) attribute. Possible values are : not_configured, scheduled, succeeded, re_scheduled, failed, skipped, not_applicable.
Supported operators : is, is_not, in, not_in

Example webhook_status[is] = "succeeded"
optional, enumerated string filter
event_type[<operator>]
To filter based on Event Type. Possible values are : plan_created, plan_updated, plan_deleted, addon_created, addon_updated, addon_deleted, coupon_created, coupon_updated, coupon_deleted, customer_created, customer_changed, customer_deleted, customer_moved_out, customer_moved_in, subscription_created, subscription_started, subscription_trial_end_reminder, subscription_activated, subscription_changed, subscription_cancellation_scheduled, subscription_cancellation_reminder, subscription_cancelled, subscription_reactivated, subscription_renewed, subscription_scheduled_cancellation_removed, subscription_shipping_address_updated, subscription_deleted, pending_invoice_created, invoice_generated, invoice_updated, invoice_deleted, credit_note_created, credit_note_updated, credit_note_deleted, subscription_renewal_reminder, transaction_created, transaction_updated, transaction_deleted, payment_succeeded, payment_failed, payment_refunded, payment_initiated, refund_initiated, netd_payment_due_reminder, card_added, card_updated, card_expiry_reminder, card_expired, card_deleted, payment_source_added, payment_source_updated, payment_source_deleted.
Supported operators : is, is_not, in, not_in

Example event_type[is] = "customer_created"
optional, enumerated string filter
source[<operator>]
To filter based on Event Source. Possible values are : admin_console, api, scheduled_job, hosted_page, portal, system, none, js_api, migration, bulk_operation, external_service.
Supported operators : is, is_not, in, not_in

Example source[is] = "hosted_page"
optional, enumerated string filter
occurred_at[<operator>]
To filter based on Event Occurred At.
Supported operators : after, before, on, between

Example occurred_at[on] = "1349116200"
optional, timestamp(UTC) in seconds filter
Resource object representing event.
always returned
next_offset
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”.
optional, string, max chars=1000

Retrieves a particular event.


NOTE : Only events that are less than null days old will be retrieved
.
Sample Request
curl  https://{site}.chargebee.com/api/v2/events/ev_8asn8QLqqQqA8 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/events/ev_8asn8QLqqQqA8 \
     -u {site_api_key}:

Sample Response [ JSON ]

{"event": { "id": "ev_8asn8QLqqQqA8", "occurred_at": 1412101820, "source": "system", "object": "event", "api_version": "v2", "content": { "customer": { "id": "8avVGOkx8U1MX", "first_name": "Benjamin", "last_name": "Ross", "email": "Benjamin@test.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1412101813, "taxability": "taxable", "updated_at": 1412101820, "resource_version": 1412101820000, "deleted": false, "object": "customer", "card_status": "valid", "primary_payment_source_id": "pm_8asn8QLqqPW96", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "tok_8asn8QLqqPPf5", "gateway": "chargebee", "gateway_account_id": "gw_8asn8QLqqJps2", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "preferred_currency_code": "USD" }, "card": { "status": "valid", "gateway": "chargebee", "gateway_account_id": "gw_8asn8QLqqJps2", "iin": "411111", "last4": "1111", "card_type": "visa", "funding_type": "credit", "expiry_month": 1, "expiry_year": 2022, "object": "card", "masked_number": "************1111", "customer_id": "8avVGOkx8U1MX", "payment_source_id": "pm_8asn8QLqqPW96" } }, "event_type": "customer_created", "webhook_status": "not_configured" }}

URL Format GET

https://{site}.chargebee.com/api/v2/events/{event_id}
Resource object representing event.
always returned

Sample admin console URL

https://{site}.chargebee.com/admin-console/events/ev_8asn8QLqqQqA8