Settings
Configure SDK
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:
- 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 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 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
The type of event provided by Chargebee. See event types for a complete list.
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 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.
Applicable only when event_source is api.
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
Filter Params
For operator usages, see the Pagination and Filtering section.
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"
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, dunning_updated, 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, omnichannel_subscription_moved_in, omnichannel_transaction_created
Supported operators : is, is_not, in, not_in
Example → event_type[is] = "customer_created"
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
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.
Note: Only events that are less than 90 days old will be retrieved.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing event