Settings
API Version
Product Catalog
Library
Configure SDK
Home
Business Entities
Customers
Subscriptions
In App Purchases - Legacy
Omnichannel
Invoices and Credit Notes
Estimates
Orders
Product Catalog
Entitlements
Usage Based Billing
Hosted Pages
Payments
Currencies
Events
Simulation Tools
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’s 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:
- Get the event
idand keep it in a persistent store such as a relational database or redis. - Check whether the event
idis already processed. - If the event has not been processed, process it; otherwise, it is a duplicate event, so it can be ignored.
- 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:
- Get the value
rv1of theresource_versionattribute from the resource in the webhook. - Get the value
rv2ofresource_versionfrom 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 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.- 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.
- Enter Username and Password and click Update Webhook.
OR
Generate a random key and have it as part of your webhook URLeg, 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 event [ JSON ]
{
"event": {
"id": "ev_16BPgETyVrQbiGhA",
"occurred_at": 1702645601,
"source": "admin_console",
"user": "sarah@sarah.com",
"object": "event",
"api_version": "v2",
"content": {
"subscription": {
"id": "16BPgETyVrQVHGh1",
"billing_period": 1,
"billing_period_unit": "month",
"customer_id": "sarah",
"status": "active",
"current_term_start": 1702578600,
"current_term_end": 1705256999,
"next_billing_at": 1705257000,
"created_at": 1702645601,
"started_at": 1702578600,
"activated_at": 1702578600,
"created_from_ip": "10.0.0.1",
"updated_at": 1702645601,
"has_scheduled_changes": false,
"channel": "web",
"resource_version": 1702645601793,
"deleted": false,
"object": "subscription",
"currency_code": "INR",
"subscription_items": [
{
"item_price_id": "cross-train-advanced-INR-1_MONTH",
"item_type": "plan",
"quantity": 1,
"quantity_in_decimal": "1.0000",
"unit_price": 11667,
"unit_price_in_decimal": "116.66667",
"amount": 11667,
"amount_in_decimal": "116.66667",
"free_quantity": 0,
"free_quantity_in_decimal": "0.0000",
"object": "subscription_item"
}
],
"due_invoices_count": 0,
"mrr": 0,
"has_scheduled_advance_invoices": false,
"override_relationship": false,
"create_pending_invoices": false,
"auto_close_invoices": true,
"business_entity_id": "16CQtCTrgrYwi9n2E"
},
"customer": {
"id": "sarah",
"auto_collection": "on",
"net_term_days": 0,
"allow_direct_debit": false,
"created_at": 1700038561,
"created_from_ip": "10.0.0.2",
"taxability": "taxable",
"updated_at": 1702645580,
"pii_cleared": "active",
"channel": "web",
"resource_version": 1702645580741,
"deleted": false,
"object": "customer",
"card_status": "valid",
"promotional_credits": 0,
"refundable_credits": 0,
"excess_payments": 0,
"unbilled_charges": 0,
"preferred_currency_code": "INR",
"mrr": 0,
"primary_payment_source_id": "pm_169vujTyVrL5fFDl",
"payment_method": {
"object": "payment_method",
"type": "card",
"reference_id": "tok_169vujTyVrL5LFDk",
"gateway": "chargebee",
"gateway_account_id": "gw_1mk51R4QrLmQtYMht",
"status": "valid"
},
"business_entity_id": "16CQtCTrgrYwi9n2E",
"tax_providers_fields": [],
"auto_close_invoices": true
},
"card": {
"status": "valid",
"gateway": "chargebee",
"gateway_account_id": "gw_1mk51R4QrLmQtYMht",
"iin": "411111",
"last4": "1111",
"card_type": "visa",
"funding_type": "credit",
"expiry_month": 12,
"expiry_year": 2024,
"created_at": 1702645580,
"updated_at": 1702645580,
"ip_address": "10.0.0.1",
"resource_version": 1702645580740,
"object": "card",
"masked_number": "************1111",
"customer_id": "boom",
"payment_source_id": "pm_169vujTyVrL5fFDl"
},
"invoice": {
"id": "203",
"customer_id": "boom",
"subscription_id": "16BPgETyVrQVHGh1",
"recurring": true,
"status": "paid",
"price_type": "tax_exclusive",
"date": 1702578600,
"due_date": 1702578600,
"net_term_days": 0,
"exchange_rate": 83.283543,
"total": 11667,
"amount_paid": 11667,
"amount_adjusted": 0,
"write_off_amount": 0,
"credits_applied": 0,
"amount_due": 0,
"paid_at": 1702645601,
"updated_at": 1702645601,
"resource_version": 1702645601783,
"deleted": false,
"object": "invoice",
"first_invoice": true,
"amount_to_collect": 0,
"round_off_amount": 0,
"new_sales_amount": 11667,
"has_advance_charges": false,
"currency_code": "INR",
"base_currency_code": "USD",
"generated_at": 1702578600,
"is_gifted": false,
"term_finalized": true,
"channel": "web",
"tax": 0,
"line_items": [
{
"id": "li_16BPgETyVrQWBGh3",
"date_from": 1702578600,
"date_to": 1705256999,
"unit_amount": 11667,
"quantity": 1,
"amount": 11667,
"pricing_model": "per_unit",
"is_taxed": false,
"tax_amount": 0,
"unit_amount_in_decimal": "116.66667",
"quantity_in_decimal": "1.0000",
"amount_in_decimal": "116.66667",
"object": "line_item",
"subscription_id": "16BPgETyVrQVHGh1",
"customer_id": "boom",
"description": "cross-train-advanced-INR-1_MONTH",
"entity_type": "plan_item_price",
"entity_id": "cross-train-advanced-INR-1_MONTH",
"metered": false,
"tax_exempt_reason": "export",
"discount_amount": 0,
"item_level_discount_amount": 0
}
],
"sub_total": 11667,
"linked_payments": [
{
"txn_id": "txn_16BPgETyVrQXVGh4",
"applied_amount": 11667,
"applied_at": 1702645601,
"txn_status": "success",
"txn_date": 1702645601,
"txn_amount": 11667
}
],
"applied_credits": [],
"adjustment_credit_notes": [],
"issued_credit_notes": [],
"linked_orders": [],
"dunning_attempts": [],
"notes": [
{
"note": "You can pay card."
}
],
"business_entity_id": "16CQtCTrgrYwi9n2E"
}
},
"event_type": "subscription_created",
"webhook_status": "not_configured",
"webhooks": [
{
"id": "whv2_Azz5aITsMVdKtVWV",
"webhook_status": "not_applicable",
"object": "webhook"
},
{
"id": "whv2_Azz5aITsMVaqCVT4",
"webhook_status": "not_applicable",
"object": "webhook"
},
{
"id": "whv2_169lhWTpiH34m3Vp8",
"webhook_status": "not_applicable",
"object": "webhook"
},
{
"id": "whv2_AzZiyPTsMVf4DUdv",
"webhook_status": "re_scheduled",
"object": "webhook"
}
]
}
}API Index URL GET
https://{site}.chargebee.com/api/v2/events
optional, string, max chars=150
The “user” that triggered the event. The value depends on the
The “user” that triggered the event. The value depends on the
source attribute:- When
sourceisadmin_console: the email address of the user that triggered the event. - When
sourceisapi,js_apiorbulk_operation: the name of the API key that was used to trigger the event. - When the
sourceisexternal_service: the name of the service that called our webhook. Eg.ADYEN,STRIPE,AMAZON_PAYMENTSetc. - When the
sourceishosted_pageorportal: theuserattribute is not passed.
optional, enumerated string
The type of event provided by Chargebee. See event types for a complete list.
The type of event provided by Chargebee. See event types for a complete list.
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.
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.
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.
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
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 Request
Sample Response [ JSON ]
URL Format GET
https://{site}.chargebee.com/api/v2/events
Input Parameters
Filter Params
For operator usages, see the Pagination and Filtering section.
optional, enumerated string filter
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, disabled
Supported operators : is, is_not, in, not_in
Example → webhook_status[is] = "succeeded"
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, disabled
Supported operators : is, is_not, in, not_in
Example → webhook_status[is] = "succeeded"
optional, enumerated string filter
Specify it if you need to fetch events of a particular type. Possible values are : coupon_created, coupon_updated, coupon_deleted, coupon_set_created, coupon_set_updated, coupon_set_deleted, coupon_codes_added, coupon_codes_deleted, coupon_codes_updated, customer_created, customer_changed, customer_deleted, customer_moved_out, customer_moved_in, promotional_credits_added, promotional_credits_deducted, subscription_created, subscription_created_with_backdating, subscription_started, subscription_trial_end_reminder, subscription_activated, subscription_activated_with_backdating, subscription_changed, subscription_trial_extended, mrr_updated, subscription_changed_with_backdating, subscription_cancellation_scheduled, subscription_cancellation_reminder, subscription_cancelled, subscription_canceled_with_backdating, subscription_reactivated, subscription_reactivated_with_backdating, subscription_renewed, subscription_items_renewed, subscription_scheduled_cancellation_removed, subscription_changes_scheduled, subscription_scheduled_changes_removed, subscription_shipping_address_updated, subscription_deleted, subscription_paused, subscription_pause_scheduled, subscription_scheduled_pause_removed, subscription_resumed, subscription_resumption_scheduled, subscription_scheduled_resumption_removed, subscription_advance_invoice_schedule_added, subscription_advance_invoice_schedule_updated, subscription_advance_invoice_schedule_removed, pending_invoice_created, pending_invoice_updated, invoice_generated, invoice_generated_with_backdating, invoice_updated, invoice_deleted, credit_note_created, credit_note_created_with_backdating, credit_note_updated, credit_note_deleted, payment_schedules_created, payment_schedules_updated, payment_schedule_scheme_created, payment_schedule_scheme_deleted, subscription_renewal_reminder, add_usages_reminder, transaction_created, transaction_updated, transaction_deleted, payment_succeeded, payment_failed, payment_refunded, payment_initiated, refund_initiated, authorization_succeeded, authorization_voided, card_added, card_updated, card_expiry_reminder, card_expired, card_deleted, payment_source_added, payment_source_updated, payment_source_deleted, payment_source_expiring, payment_source_expired, payment_source_locally_deleted, virtual_bank_account_added, virtual_bank_account_updated, virtual_bank_account_deleted, token_created, token_consumed, token_expired, unbilled_charges_created, unbilled_charges_voided, unbilled_charges_deleted, unbilled_charges_invoiced, order_created, order_updated, order_cancelled, order_delivered, order_returned, order_ready_to_process, order_ready_to_ship, order_deleted, order_resent, quote_created, quote_updated, quote_deleted, tax_withheld_recorded, tax_withheld_deleted, tax_withheld_refunded, gift_scheduled, gift_unclaimed, gift_claimed, gift_expired, gift_cancelled, gift_updated, hierarchy_created, hierarchy_deleted, payment_intent_created, payment_intent_updated, contract_term_created, contract_term_renewed, contract_term_terminated, contract_term_completed, contract_term_cancelled, item_family_created, item_family_updated, item_family_deleted, item_created, item_updated, item_deleted, item_price_created, item_price_updated, item_price_deleted, attached_item_created, attached_item_updated, attached_item_deleted, differential_price_created, differential_price_updated, differential_price_deleted, feature_created, feature_updated, feature_deleted, feature_activated, feature_reactivated, feature_archived, item_entitlements_updated, entitlement_overrides_updated, entitlement_overrides_removed, item_entitlements_removed, entitlement_overrides_auto_removed, subscription_entitlements_created, subscription_entitlements_updated, business_entity_created, business_entity_updated, business_entity_deleted, customer_business_entity_changed, subscription_business_entity_changed, purchase_created, voucher_created, voucher_expired, voucher_create_failed, item_price_entitlements_updated, item_price_entitlements_removed, subscription_ramp_created, subscription_ramp_deleted, subscription_ramp_applied, subscription_ramp_drafted, subscription_ramp_updated, price_variant_created, price_variant_updated, price_variant_deleted, customer_entitlements_updated, subscription_moved_in, subscription_moved_out, subscription_movement_failed, omnichannel_subscription_created, omnichannel_subscription_item_renewed, omnichannel_subscription_item_downgraded, omnichannel_subscription_item_expired, omnichannel_subscription_item_cancellation_scheduled, omnichannel_subscription_item_scheduled_cancellation_removed, omnichannel_subscription_item_resubscribed, omnichannel_subscription_item_upgraded, omnichannel_subscription_item_cancelled, omnichannel_subscription_imported, omnichannel_subscription_item_grace_period_started, omnichannel_subscription_item_grace_period_expired, omnichannel_subscription_item_dunning_started, omnichannel_subscription_item_dunning_expired, rule_created, rule_updated, rule_deleted, record_purchase_failed, omnichannel_subscription_item_change_scheduled, omnichannel_subscription_item_scheduled_change_removed, omnichannel_subscription_item_reactivated, sales_order_created, sales_order_updated, omnichannel_subscription_item_changed, omnichannel_subscription_item_paused, omnichannel_subscription_item_resumed, omnichannel_one_time_order_created, omnichannel_one_time_order_item_cancelled, usage_file_ingested, omnichannel_subscription_item_pause_scheduled
Supported operators : is, is_not, in, not_in
Example → event_type[is] = "customer_created"
Specify it if you need to fetch events of a particular type. Possible values are : coupon_created, coupon_updated, coupon_deleted, coupon_set_created, coupon_set_updated, coupon_set_deleted, coupon_codes_added, coupon_codes_deleted, coupon_codes_updated, customer_created, customer_changed, customer_deleted, customer_moved_out, customer_moved_in, promotional_credits_added, promotional_credits_deducted, subscription_created, subscription_created_with_backdating, subscription_started, subscription_trial_end_reminder, subscription_activated, subscription_activated_with_backdating, subscription_changed, subscription_trial_extended, mrr_updated, subscription_changed_with_backdating, subscription_cancellation_scheduled, subscription_cancellation_reminder, subscription_cancelled, subscription_canceled_with_backdating, subscription_reactivated, subscription_reactivated_with_backdating, subscription_renewed, subscription_items_renewed, subscription_scheduled_cancellation_removed, subscription_changes_scheduled, subscription_scheduled_changes_removed, subscription_shipping_address_updated, subscription_deleted, subscription_paused, subscription_pause_scheduled, subscription_scheduled_pause_removed, subscription_resumed, subscription_resumption_scheduled, subscription_scheduled_resumption_removed, subscription_advance_invoice_schedule_added, subscription_advance_invoice_schedule_updated, subscription_advance_invoice_schedule_removed, pending_invoice_created, pending_invoice_updated, invoice_generated, invoice_generated_with_backdating, invoice_updated, invoice_deleted, credit_note_created, credit_note_created_with_backdating, credit_note_updated, credit_note_deleted, payment_schedules_created, payment_schedules_updated, payment_schedule_scheme_created, payment_schedule_scheme_deleted, subscription_renewal_reminder, add_usages_reminder, transaction_created, transaction_updated, transaction_deleted, payment_succeeded, payment_failed, payment_refunded, payment_initiated, refund_initiated, authorization_succeeded, authorization_voided, card_added, card_updated, card_expiry_reminder, card_expired, card_deleted, payment_source_added, payment_source_updated, payment_source_deleted, payment_source_expiring, payment_source_expired, payment_source_locally_deleted, virtual_bank_account_added, virtual_bank_account_updated, virtual_bank_account_deleted, token_created, token_consumed, token_expired, unbilled_charges_created, unbilled_charges_voided, unbilled_charges_deleted, unbilled_charges_invoiced, order_created, order_updated, order_cancelled, order_delivered, order_returned, order_ready_to_process, order_ready_to_ship, order_deleted, order_resent, quote_created, quote_updated, quote_deleted, tax_withheld_recorded, tax_withheld_deleted, tax_withheld_refunded, gift_scheduled, gift_unclaimed, gift_claimed, gift_expired, gift_cancelled, gift_updated, hierarchy_created, hierarchy_deleted, payment_intent_created, payment_intent_updated, contract_term_created, contract_term_renewed, contract_term_terminated, contract_term_completed, contract_term_cancelled, item_family_created, item_family_updated, item_family_deleted, item_created, item_updated, item_deleted, item_price_created, item_price_updated, item_price_deleted, attached_item_created, attached_item_updated, attached_item_deleted, differential_price_created, differential_price_updated, differential_price_deleted, feature_created, feature_updated, feature_deleted, feature_activated, feature_reactivated, feature_archived, item_entitlements_updated, entitlement_overrides_updated, entitlement_overrides_removed, item_entitlements_removed, entitlement_overrides_auto_removed, subscription_entitlements_created, subscription_entitlements_updated, business_entity_created, business_entity_updated, business_entity_deleted, customer_business_entity_changed, subscription_business_entity_changed, purchase_created, voucher_created, voucher_expired, voucher_create_failed, item_price_entitlements_updated, item_price_entitlements_removed, subscription_ramp_created, subscription_ramp_deleted, subscription_ramp_applied, subscription_ramp_drafted, subscription_ramp_updated, price_variant_created, price_variant_updated, price_variant_deleted, customer_entitlements_updated, subscription_moved_in, subscription_moved_out, subscription_movement_failed, omnichannel_subscription_created, omnichannel_subscription_item_renewed, omnichannel_subscription_item_downgraded, omnichannel_subscription_item_expired, omnichannel_subscription_item_cancellation_scheduled, omnichannel_subscription_item_scheduled_cancellation_removed, omnichannel_subscription_item_resubscribed, omnichannel_subscription_item_upgraded, omnichannel_subscription_item_cancelled, omnichannel_subscription_imported, omnichannel_subscription_item_grace_period_started, omnichannel_subscription_item_grace_period_expired, omnichannel_subscription_item_dunning_started, omnichannel_subscription_item_dunning_expired, rule_created, rule_updated, rule_deleted, record_purchase_failed, omnichannel_subscription_item_change_scheduled, omnichannel_subscription_item_scheduled_change_removed, omnichannel_subscription_item_reactivated, sales_order_created, sales_order_updated, omnichannel_subscription_item_changed, omnichannel_subscription_item_paused, omnichannel_subscription_item_resumed, omnichannel_one_time_order_created, omnichannel_one_time_order_item_cancelled, usage_file_ingested, omnichannel_subscription_item_pause_scheduled
Supported operators : is, is_not, in, not_in
Example → event_type[is] = "customer_created"
optional, enumerated string filter
Source of the event. 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"
Source of the event. 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"
Returns
event event
always returned required
Resource object representing event
Resource object representing event
next_offset
always returned optional, string, max chars=1000
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`.
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.
Note: Only events that are less than 90 days old will be retrieved.
Sample Request
Sample Response [ JSON ]
URL Format GET
https://{site}.chargebee.com/api/v2/events/{event-id}
Returns
event event
always returned required
Resource object representing event
Resource object representing event
Sample admin console URL
https://{site}.chargebee.com/admin-console/events/123x