Events

API Version

Product Catalog

Library

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

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 ]

{
    "event": {
        "api_version": "v1",
        "content": {
            "customer": {
                "account_credits": 0,
                "allow_direct_debit": false,
                "auto_collection": "on",
                "card_status": "no_card",
                "created_at": 1517506759,
                "excess_payments": 0,
                "id": "__test__5SK0bLNFRFuCIi8Nj",
                "object": "customer",
                "refundable_credits": 0,
                "taxability": "taxable"
            },
            "subscription": {
                "created_at": 1517506759,
                "due_invoices_count": 0,
                "has_scheduled_changes": false,
                "id": "__test__5SK0bLNFRFuCIi8Nj",
                "object": "subscription",
                "plan_id": "plan1",
                "plan_quantity": 1,
                "started_at": 1517506759,
                "status": "in_trial",
                "trial_end": 1518802759,
                "trial_start": 1517506759
            }
        },
        "event_type": "subscription_created",
        "id": "ev___test__5SK0bLNFRFuCIipNm",
        "object": "event",
        "occurred_at": 1517506759,
        "source": "api",
        "user": "full_access_key_v1",
        "webhook_status": "scheduled"
    }
}

API Index URL GET

https://{site}.chargebee.com/api/v1/events

id

string, max chars=40
Uniquely identifies a event

occurred_at

timestamp(UTC) in seconds
Timestamp indicating when this event had occurred.

source

enumerated string, default=none
Source of the event

Possible values are

user

optional, string, max chars=150
The “user” that triggered the event. The value depends on the source attribute:

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 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 for all the event types provided by us currently.

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 values are

content

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.

webhooks
Show attributes [+]

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.

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.

card_added

Triggered when a card is added for a customer.

›

card_deleted

Triggered when a card is deleted for a customer.

›

card_expired

Triggered when the card for a customer has expired.

›

card_expiring

Triggered when the customer's credit card is expiring soon. Triggered 30 days before the expiry date.

›

card_updated

Triggered when the card is updated for a customer.

›

customer_changed

Triggered when a customer is changed.

›

customer_created

Triggered when a customer is created.

›

customer_deleted

Triggered when a customer is deleted.

›

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_deleted

Event triggered when an invoice is deleted.

›

invoice_generated

Event triggered when a new invoice is created except when created with status as pending. For pending invoices, this event is triggered when the invoice is closed.

›

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.

›

payment_failed

Triggered when the payment collection fails.

›

payment_initiated

Triggered when a payment is initiated via direct debit.

›

payment_refunded

Triggered when a payment refund is made.

›

payment_succeeded

Triggered when the payment is successfully collected.

›

refund_initiated

Triggered when a refund is initiated via direct debit.

›

subscription_activated

Triggered after the subscription has been moved from "Trial" to "Active" state.

›

subscription_cancellation_scheduled

Triggered when subscription is scheduled to cancel at end of current term.

›

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_cancelling

Triggered 6 days prior to the scheduled cancellation date.

›

subscription_changed

Triggered when the subscription's recurring items are changed.

›

subscription_created

Triggered when a new subscription is created.

›

subscription_deleted

Triggered when a subscription is deleted.

›

subscription_reactivated

Triggered when the subscription is moved from cancelled status to active or in_trial.

›

subscription_renewal_reminder

Triggered 3 days before each subscription's renewal.

›

subscription_renewed

Triggered when the subscription is renewed from the current term.

›

subscription_scheduled_cancellation_removed

Triggered when scheduled cancellation is removed for the subscription.

›

subscription_shipping_address_updated

Triggered when shipping address is added or updated for a subscription.

›

subscription_started

Triggered when a 'future' subscription gets started.

›

subscription_trial_ending

Triggered 6 days prior to the trial period's end date.

›

subscription_trial_extended

Trial Extension

›

transaction_created

Triggered when a transaction is recorded.

›

transaction_deleted

Triggered when a transaction is deleted.

›

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.

›

id

string, max chars=40
Uniquely identifies a event

occurred_at

timestamp(UTC) in seconds
Timestamp indicating when this event had occurred.

source

enumerated string, default=none
Source of the event

Possible values are

user

optional, string, max chars=150
The “user” that triggered the event. The value depends on the source attribute:

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 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 for all the event types provided by us currently.

Possible values are

api_version

Possible values are

content

webhooks

Retrieves list of events.

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/events \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     -d "event_type[in]"="subscription_created", "customer_created"

copy

Click to Copy

Sample Response [ JSON ]

{
    "list": [
        {
            "event": {
                "api_version": "v1",
                "content": {
                    "customer": {
                        "account_credits": 0,
                        "allow_direct_debit": false,
                        "auto_collection": "on",
                        "card_status": "no_card",
                        "created_at": 1517506759,
                        "excess_payments": 0,
                        "id": "__test__5SK0bLNFRFuCIi8Nj",
                        "object": "customer",
                        "refundable_credits": 0,
                        "taxability": "taxable"
                    },
                    "subscription": {
                        "created_at": 1517506759,
                        "due_invoices_count": 0,
                        "has_scheduled_changes": false,
                        "id": "__test__5SK0bLNFRFuCIi8Nj",
                        "object": "subscription",
                        "plan_id": "plan1",
                        "plan_quantity": 1,
                        "started_at": 1517506759,
                        "status": "in_trial",
                        "trial_end": 1518802759,
                        "trial_start": 1517506759
                    }
                },
                "event_type": "subscription_created",
                "id": "ev___test__5SK0bLNFRFuCIipNm",
                "object": "event",
                "occurred_at": 1517506759,
                "source": "api",
                "user": "full_access_key_v1",
                "webhook_status": "scheduled"
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v1/events

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set 'offset' to the value of 'next_offset' obtained in the previous iteration of the API call.

start_time[]

optional, timestamp(UTC) in seconds
Returns only the events that occured at/after this time.

end_time[]

optional, timestamp(UTC) in seconds
Returns only the events that occured at/before this time.

webhook_status[]

optional, enumerated string
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

event_type[]

optional, enumerated string
Specify it if you need to fetch events of a particular type.

Possible values are

event

always returned
Resource object representing event

next_offset

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`.

Retrieves a specific event identified by a unique event identifier.

Sample Request

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v1/events/ev___test__5SK0bLNFRFuCIloNr \
     -u {site_api_key}:

copy

Click to Copy

Sample Response [ JSON ]

{
    "event": {
        "api_version": "v1",
        "content": {
            "customer": {
                "account_credits": 0,
                "allow_direct_debit": false,
                "auto_collection": "off",
                "card_status": "no_card",
                "created_at": 1517506760,
                "excess_payments": 0,
                "id": "__test__5SK0bLNFRFuCIkgNn",
                "object": "customer",
                "refundable_credits": 0,
                "taxability": "taxable"
            }
        },
        "event_type": "customer_created",
        "id": "ev___test__5SK0bLNFRFuCIloNr",
        "object": "event",
        "occurred_at": 1517506760,
        "source": "api",
        "user": "full_access_key_v1",
        "webhook_status": "scheduled"
    }
}

URL Format GET

https://{site}.chargebee.com/api/v1/events/{event-id}

event

always returned
Resource object representing event

Sample admin console URL

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

Securing your Webhook URL:

Sample event [ JSON ]

API Index URL GET

Model Class

Event attributes

Event types

Consent Fields for Event

Custom Fields for Event

List events ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve an event ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL