# Events > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). ### Introduction[](#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[](#webhooks) If webhooks have been [configured](https://www.chargebee.com/docs/webhook_settings.html#configure-webhooks) 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](https://www.chargebee.com/docs/webhook_settings.html#automatic-retries). The webhook call is an HTTP POST with content type `application/json`. #### Retries & Duplicate Handling[](#retries-duplicate-handling) To mark a webhook notification successful, we expect the [HTTP status code](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes) to be `2XX` from your webhook URL. If we don't receive `2XX` response code, we [retry](https://www.chargebee.com/docs/webhook_settings.html#automatic-retries) calling your webhook with a progressively increasing delay for the next 2 days. You could also [resend](https://www.chargebee.com/docs/webhook_settings.html#automatic-retries) 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](/docs/api/events/event-object#id) parameter since its value uniquely identifies an event. For example, your application could 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 then process the event; otherwise, it is a duplicate event so can be ignored. 4. 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[](#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: 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`](/docs/api/events/event-object#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[](#securing-your-webhook-url) You can have **basic authentication** for the webhook url. 1. 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.** 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](/docs/api/events/retrieve-an-event) API call. #### Webhook IP Addresses[](#webhook-ip-addresses) Webhooks from Chargebee originate from a [specific set of IP addresses](/docs/api/v2/pcv-1/webhooks). ## Sample Event ```json { "event": { "api_version": "v2", "content": { "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "no_card", "created_at": 1517505957, "deleted": false, "excess_payments": 0, "id": "__test__KyVnHhSBWm4Xv2rm", "net_term_days": 0, "object": "customer", "pii_cleared": "active", "preferred_currency_code": "USD", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517505957000, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517505957 }, "subscription": { "billing_period": 1, "billing_period_unit": "month", "created_at": 1517505957, "currency_code": "USD", "customer_id": "__test__KyVnHhSBWm4Xv2rm", "deleted": false, "due_invoices_count": 0, "has_scheduled_changes": false, "id": "__test__KyVnHhSBWm4Xv2rm", "next_billing_at": 1518801957, "object": "subscription", "plan_amount": 1500, "plan_free_quantity": 0, "plan_id": "plan1", "plan_quantity": 1, "plan_unit_price": 1500, "resource_version": 1517505957000, "started_at": 1517505957, "status": "in_trial", "trial_end": 1518801957, "trial_start": 1517505957, "updated_at": 1517505957 } }, "event_type": "subscription_created", "id": "ev___test__KyVnHhSBWm4am2rp", "object": "event", "occurred_at": 1517505957, "source": "api", "user": "full_access_key_v1", "webhook_status": "scheduled" } } ``` ## Events attributes ## Input Parameters - `id` (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 Possible enum values: - `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](https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html) - `system` Operation that are triggered by ChargeBee System - `none` If no source can be identified for an operation - `js_api` Operation made through the JS API - `migration` Deprecated - `bulk_operation` Operation that are triggerd through bulk operation. - `external_service` Operation that are triggered via webhook - `user` (optional, string, max chars=150) The "user"" that triggered the event. The value depends on the `source` - When `source` is `admin_console`: the email address of the user that triggered the event. - When `source` is `api`, `js_api` or `bulk_operation`: the [name](https://www.chargebee.com/docs/api_keys.html#create-an-api-key) of the API key that was used to trigger the event. - When the `source` is `external_service`: the name of the service that called our webhook. Eg. `ADYEN`, `STRIPE`, `AMAZON_PAYMENTS` etc. - When the `source` is `hosted_page` or `portal`: the `user` attribute is not passed. - `event_type` (optional, enumerated string) The types of event provided by chargebee. Refer [event types](/docs/api/v2/pcv-1/events/event-types) for all the event types provided by us currently. Possible enum values: - `plan_created` Sent when a plan is created. - `plan_updated` Sent when a plan is changed. - `plan_deleted` Sent when a plan is deleted. - `addon_created` Sent when a addon is created. - `addon_updated` Sent when a addon is changed. - `addon_deleted` Sent when a addon is deleted. - `coupon_created` Sent when a coupon is created. - `coupon_updated` Sent when a coupon is changed. - `coupon_deleted` Sent when a coupon is deleted. - `coupon_set_created` Sent when a coupon set is created - `coupon_set_updated` Sent when a coupon set is changed - `coupon_set_deleted` Sent when a coupon set is deleted - `coupon_codes_added` Sent when coupon codes are added in coupon set - `coupon_codes_deleted` Sent when coupon codes are deleted in coupon set - `coupon_codes_updated` Sent when coupon codes are updated - `customer_created` Sent when a customer is created. This event happens when only a new customer is created or when a customer is automatically created during new subscription creation. - `customer_changed` Sent when a customer is changed - `customer_deleted` Sent when a customer is deleted - `customer_moved_out` Sent when a customer is copied to another site - `customer_moved_in` Sent when a customer is copied from another site - `promotional_credits_added` Sent when a customer prmotion credits added - `promotional_credits_deducted` Sent when a customer prmotion credits deducted - `subscription_created` Sent when a new subscription is created. - `subscription_created_with_backdating` Sent when a new subscription is created with backdating. - `subscription_started` Sent when a 'future' subscription gets started at the scheduled date. - `subscription_trial_end_reminder` Sent when the customer's trial period is about to end. - `subscription_activated` Sent after the subscription has been moved from trial to active state - `subscription_activated_with_backdating` Sent after the subscription changes to `active` from another `status`, while the change is backdated. - `subscription_changed` Sent after the subscription's recurring items have been changed - `subscription_trial_extended` Trial Extension - `mrr_updated` Sent when either of MRR or CMRR of a subscription changes - `subscription_changed_with_backdating` Sent after the subscription's recurring items have been changed with backdated date - `subscription_cancellation_scheduled` Sent when subscription is scheduled to cancel at end of current term - `subscription_cancellation_reminder` Sent when the customer's subscription is nearing it's scheduled cancellation date. - `subscription_cancelled` Sent when the subscription gets cancelled. If cancelled due to non payment or card not present, the subscription will have the possible reason as 'cancel\_reason'. - `subscription_canceled_with_backdating` Sent when the subscription gets cancelled. If cancelled due to non payment or card not present, the subscription will have the possible reason as 'cancel\_reason'. - `subscription_reactivated` Sent when the subscription is moved from cancelled state to active or in\_trial state - `subscription_reactivated_with_backdating` Sent when the subscription is moved from cancelled state to active or in\_trial state with past date - `subscription_renewed` Sent when the subscription is renewed from the current term. - `subscription_items_renewed` Sent when one or more Subscription Items are renewed - `subscription_scheduled_cancellation_removed` Sent when scheduled cancellation is removed for the subscription. - `subscription_changes_scheduled` Sent when subscription changes are scheduled for later. Changes will be applied at the end of current term. - `subscription_scheduled_changes_removed` Sent when scheduled change for the subscription is removed. - `subscription_shipping_address_updated` Triggered when shipping address is added or updated for a subscription. - `subscription_deleted` Sent when a subscription has been deleted - `subscription_paused` Sent when the subscription is paused. - `subscription_pause_scheduled` Sent when the subscription is scheduled to pause. - `subscription_scheduled_pause_removed` Triggered when scheduled pause is removed for the subscription. - `subscription_resumed` Sent when the subscription is moved from paused state to active state - `subscription_resumption_scheduled` Triggered when the subscription resumption is scheduled. - `subscription_scheduled_resumption_removed` Triggered when scheduled resumption is removed for the subscription. - `subscription_advance_invoice_schedule_added` Triggered when advance invoice is scheduled for a subscription. - `subscription_advance_invoice_schedule_updated` Triggered when scheduled advance invoice is updated for a subscription. - `subscription_advance_invoice_schedule_removed` Triggered when scheduled advance invoice is removed for a subscription. - `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. - `pending_invoice_updated` Triggered when you make the following changes to a pending invoice: add a charge, add a non-recurring addon, or delete a line item. - `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_generated_with_backdating` Event triggered when a new invoice is generated with past date as invoice date. - `invoice_updated` Triggered when changes are made to a finalized invoice, including voiding, deletion, invoice address updates, status changes, and payment changes such as applying or removing a payment, applying or removing a credit, and credit note creation. pending\_invoice\_updated is triggered for changes specific to pending invoices; invoice\_updated covers all other invoice changes. - `invoice_deleted` Event triggered when an invoice is deleted. - `credit_note_created` Sent when a credit note is created - `credit_note_created_with_backdating` Sent when a credit note is created with past date as credit note date - `credit_note_updated` Sent when a credit note is updated - `credit_note_deleted` Sent when a credit note is deleted - `subscription_renewal_reminder` Sent before each subscription's renewal based on plan's period - `transaction_created` Triggered when a transaction is recorded - `transaction_updated` Triggered when a transaction is updated. E.g. (1) When a transaction is removed, (2) or when an excess payment is applied on an invoice, (3) or when amount\_capturable gets updated. - `transaction_deleted` Triggered when a transaction is deleted. - `payment_succeeded` Sent when the payment is successfully collected - `payment_failed` Sent when attempt to charge customer's credit card fails - `dunning_updated` Sent when dunning is paused for an invoice - `payment_refunded` Sent when a payment refund is made - `payment_initiated` Sent when a payment is initiated via direct debit - `refund_initiated` Sent when a refund is initiated via direct debit - `authorization_succeeded` Triggered when a authorization transaction is created. - `authorization_voided` Triggered when a authorization transaction is voided. Authorization can be voided either manually or when blocked funds are released by the gateway after a certain period of time. - `card_added` Sent when a card is added for a customer. - `card_updated` Sent when the card is updated for a customer. - `card_expiry_reminder` Sent when the customer's credit card is expiring soon. Sent 30 days before the expiry date. - `card_expired` Sent when a card for a customer is expired - `card_deleted` Sent when a card is deleted for a customer - `payment_source_added` Sent when a payment source is added for a customer. - `payment_source_updated` Sent when the payment source is updated for a customer or when role is assigned to the payment source. - `payment_source_deleted` Sent when a payment source is deleted for a customer - `payment_source_expiring` Sent when the customer's payment source is expiring soon. Sent 30 days before the expiry date. - `payment_source_expired` Sent when a payment source for a customer is expired - `payment_source_locally_deleted` Sent when a payment source for a customer removed from Chargebee - `virtual_bank_account_added` Sent when a virtual bank account is added for a customer. - `virtual_bank_account_updated` Sent when the virtual bank account is updated for a customer. - `virtual_bank_account_deleted` Sent when a virtual bank account is deleted for a customer. - `token_created` Sent when a Token is created - `token_consumed` Sent when a Token is consumed - `token_expired` Sent when a Token is expired - `unbilled_charges_created` Triggered when unbilled charges are created - `unbilled_charges_voided` Triggered when unbilled charges are voided - `unbilled_charges_deleted` Triggered when unbilled charges are deleted - `unbilled_charges_invoiced` Triggered when unbilled charges are invoiced - `order_created` Triggered when order is created - `order_updated` Triggered when order is updated - `order_cancelled` Triggered when order is cancelled - `order_delivered` Triggered when order is marked as delivered - `order_returned` Triggered when order is marked as returned - `order_ready_to_process` Triggered when order reaches it's order date - `order_ready_to_ship` Triggered when order reaches it's shipping date - `order_deleted` Triggered when order is deleted - `order_resent` Triggered when order is resent - `quote_created` Triggered when quote is created - `quote_updated` Triggered when quote is updated - `quote_deleted` Triggered when quote is deleted - `tax_withheld_recorded` Triggered when a tax withheld is recorded for an invoice - `tax_withheld_deleted` Triggered when a tax withheld is deleted - `tax_withheld_refunded` Sent when a tax withheld refund is made - `gift_scheduled` Triggered when a new gift is created - `gift_unclaimed` Triggered when a new gift is unclaimed and is ready to be claimed - `gift_claimed` Triggered when a gift is claimed - `gift_expired` Triggered when a gift expires - `gift_cancelled` Triggered when a gift is cancelled. - `gift_updated` Triggered when a gift is updated - `hierarchy_created` Triggered when a hierarchy is created - `hierarchy_deleted` Triggered when a hierarchy is deleted - `payment_intent_created` Sent when a Payment intent is created - `payment_intent_updated` Sent when a Payment intent is updated - `contract_term_created` Triggered when new contract term is created - `contract_term_renewed` Triggered when new contract term is renewed - `contract_term_terminated` Triggered when contract term is terminated - `contract_term_completed` Triggered when contract term is completed - `contract_term_cancelled` Triggered when contract term is cancelled - `voucher_created` Triggered when a payment voucher is created - `voucher_expired` Triggered when a payment voucher is expired - `voucher_create_failed` Triggered when a payment voucher creation is failed - `subscription_ramp_created` Triggered when a subscription ramp is created. - `subscription_ramp_deleted` Triggered when a subscription ramp is deleted. - `subscription_ramp_applied` Triggered when a subscription ramp is applied. - `subscription_ramp_drafted` Triggered when a subscription ramp is moved to draft status. - `subscription_ramp_updated` Triggered when a subscription ramp is updated. - `subscription_moved_in` Triggered when a subscription is moved from another customer - `subscription_moved_out` Triggered when a subscription is moved to another customer - `subscription_movement_failed` Triggered when a subscription movement fails - `omnichannel_subscription_created` Triggered when an omnichannel subscription is created - `omnichannel_subscription_item_renewed` Triggered when an omnichannel subscription item is renewed - `omnichannel_subscription_item_downgraded` Triggered when an omnichannel subscription item is downgraded - `omnichannel_subscription_item_expired` Triggered when an omnichannel subscription item is expired - `omnichannel_subscription_item_cancellation_scheduled` Triggered when an omnichannel subscription item is scheduled for cancellation - `omnichannel_subscription_item_scheduled_cancellation_removed` Triggered when an omnichannel subscription item scheduled cancellation is removed - `omnichannel_subscription_item_resubscribed` Triggered when an omnichannel subscription item is resubscribed - `omnichannel_subscription_item_upgraded` Triggered when an omnichannel subscription item is upgraded - `omnichannel_subscription_item_cancelled` Triggered when an omnichannel subscription item is cancelled - `omnichannel_subscription_imported` Triggered when an omnichannel subscription is imported - `omnichannel_subscription_item_grace_period_started` Triggered when an omnichannel subscription item's grace period has started - `omnichannel_subscription_item_grace_period_expired` Triggered when an omnichannel subscription item's grace period has expired - `omnichannel_subscription_item_dunning_started` Triggered when an omnichannel subscription item's dunning has started - `omnichannel_subscription_item_dunning_expired` Triggered when an omnichannel subscription item's dunning has expired - `rule_created` Triggered when a rule is created - `rule_updated` Triggered when a rule is updated - `rule_deleted` Triggered when a rule is deleted - `record_purchase_failed` Triggered when an omnichannel record purchase fails - `omnichannel_subscription_item_change_scheduled` Triggered when an omnichannel subscription item change is scheduled - `omnichannel_subscription_item_scheduled_change_removed` Triggered when an omnichannel subscription item scheduled change is removed - `omnichannel_subscription_item_reactivated` Triggered when an omnichannel subscription item is reactivated - `sales_order_created` Triggered when a sales order is created - `sales_order_updated` Triggered when a sales order is updated - `omnichannel_subscription_item_changed` Triggered when an omnichannel subscription item is changed - `omnichannel_subscription_item_paused` Triggered when an omnichannel subscription item is paused - `omnichannel_subscription_item_resumed` Triggered when an omnichannel subscription item is resumed - `omnichannel_one_time_order_created` Triggered when an omnichannel one time order is created - `omnichannel_one_time_order_item_cancelled` Triggered when an omnichannel one time order item is cancelled - `omnichannel_subscription_item_pause_scheduled` Triggered when an omnichannel subscription item is scheduled for pause - `vault_token_created` Triggered when a payment method is tokenized and stored in the vault. - `vault_token_updated` Triggered when a vaulted payment method is updated. - `vault_token_deleted` Triggered when a vaulted payment method is deleted from the vault. - `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. 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](/docs/api/v2/pcv-1/events/event-types). 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](/docs/api/advanced-features). **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. - `id` (required, string, max chars=40) Uniquely identifies a webhook - `webhook_status` (required, enumerated string) - **When the event resource is retrieved via API:** Represents the status of the webhook call made to this webhook. - **When the event resource is passed as part of a webhook call:** The `webhooks` object is unavailable on the first webhook call for the event. For subsequent calls, this attribute holds the status from after the last retry. Possible enum values: - `not_configured` Webhook was not configured when this event occurred - `scheduled` Webhook call has been scheduled. - `succeeded` Webhook call was successful. - `re_scheduled` Webhook call has been rescheduled due failure(s) in previous call(s) - `failed` Webhook call has been suspended after the all retries have resulted in failure. - `skipped` Skipped as specified in request - `not_applicable` Webhook call is not applicable for this event. - `disabled` Disabled as no longer used - `rate_limited` Webhook call was rate limited.