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 ]
{
"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
string, max chars=40
Uniquely identifies a event
timestamp(UTC) in seconds
Timestamp indicating when this event had occurred.
enumerated string, default=noneSource of the event
Possible values are
admin_consoleOperation made through the Chargebee admin UI.apiOperation made through the API.scheduled_jobOperation made through the Scheduled Jobs.hosted_pageOperation made through the Hosted Pages.portalOperation made through Self-Serve Portal.systemOperation that are triggered by ChargeBee System.noneIf no source can be identified for an operation.js_apiOperation made through the JS API.migrationDeprecated.bulk_operationOperation that are triggerd through bulk operation. Show all values[+]
optional, string, max chars=150The “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.
optional, enumerated stringThe types of event provided by chargebee. Refer
event types for all the event types provided by us currently.
optional, enumerated string, default=v1The 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
v1Chargebee API version V1.v2Chargebee API version V2.
jsonobjectThe 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, 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.
string, max chars=40
Uniquely identifies a webhook
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 values are
not_configuredWebhook was not configured when this event occurredscheduledWebhook 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 requestnot_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.
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.
Triggered when a customer is created.
customer, card(optional)
Triggered when a customer is changed.
customer, card(optional)
Triggered when a customer is deleted.
customer, card(optional), subscriptions(optional)
Triggered when a new subscription is created.
subscription, customer, card(optional), invoice(optional)
Triggered when a 'future' subscription gets started.
subscription, customer, card(optional), invoice(optional)
subscription_trial_ending
Triggered 6 days prior to the trial period's end date.
subscription, customer, card(optional)
Triggered after the subscription has been moved from "Trial" to "Active" state.
subscription, customer, card(optional), invoice(optional)
Triggered when the subscription's recurring items are changed.
subscription, customer, card(optional), invoice(optional)
subscription_trial_extended
Trial Extension
subscription, customer, card(optional)
subscription_cancellation_scheduled
Triggered when subscription is scheduled to cancel at end of current term.
subscription, customer, card(optional)
Triggered 6 days prior to the scheduled cancellation date.
subscription, customer, card(optional)
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), invoice(optional)
Triggered when the subscription is moved from `cancelled` `status` to `active` or `in_trial`.
subscription, customer, card(optional), invoice(optional)
Triggered when the subscription is renewed from the current term.
subscription, customer, card(optional), invoice(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)
Triggered when a subscription is deleted.
subscription, customer, card(optional)
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
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
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
Event triggered when an invoice is deleted.
invoice
subscription_renewal_reminder
Triggered 3 days before each subscription's renewal.
subscription, customer, card(optional)
Triggered when a transaction is recorded.
transaction
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
Triggered when a transaction is deleted.
transaction
Triggered when the payment is successfully collected.
transaction, invoice, customer, subscription(optional), card(optional)
Triggered when the payment collection fails.
transaction, invoice, customer, subscription(optional), card(optional)
Triggered when a payment refund is made.
transaction, invoice, customer, subscription(optional), card(optional)
Triggered when a payment is initiated via direct debit.
transaction, invoice, customer, subscription(optional), card(optional)
Triggered when a refund is initiated via direct debit.
transaction, invoice, customer, subscription(optional), card(optional)
Triggered when a card is added for a customer.
customer, card(optional)
Triggered when the card is updated for a customer.
customer, card(optional)
Triggered when the customer's credit card is expiring soon. Triggered 30 days before the expiry date.
customer, card(optional)
Triggered when the card for a customer has expired.
customer, card(optional)
Triggered when a card is deleted for a customer.
customer, card(optional)
Retrieves list of events.
Sample Request
curl https://{site}.chargebee.com/api/v1/events \
-G \
-u {site_api_key}:\
--data-urlencode limit=2 \
--data-urlencode event_type[in]="["subscription_created","customer_created"]"
copy
curl https://{site}.chargebee.com/api/v1/events \
-G \
-u {site_api_key}:\
--data-urlencode limit=2 \
--data-urlencode event_type[in]="["subscription_created","customer_created"]"
Sample Response [ JSON ]
Show more...
{"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
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
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.
optional, timestamp(UTC) in seconds
Returns only the events that occured at/after this time.
optional, timestamp(UTC) in seconds
Returns only the events that occured at/before this time.
optional, enumerated stringReturns 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_configuredWebhook was not configured when this event occurredscheduledWebhook 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 requestnot_applicableWebhook call is not applicable for this event.
optional, enumerated stringSpecify it if you need to fetch events of a particular type.
Possible values are
customer_createdSent 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_changedSent when a customer is changedcustomer_deletedSent when a customer is deletedsubscription_createdSent when a new subscription is created.subscription_startedSent when a 'future' subscription gets started at the scheduled date.subscription_trial_endingSent when the customer's trial period is about to end.subscription_activatedSent after the subscription has been moved from trial to active statesubscription_changedSent after the subscription's recurring items have been changedsubscription_trial_extendedTrial Extensionsubscription_cancellation_scheduledSent when subscription is scheduled to cancel at end of current termsubscription_cancellingSent when the customer's subscription is nearing it's scheduled cancellation date.subscription_cancelledSent 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_reactivatedSent when the subscription is moved from cancelled state to active or in_trial statesubscription_renewedSent when the subscription is renewed from the current term.subscription_scheduled_cancellation_removedSent when scheduled cancellation is removed for the subscription.subscription_shipping_address_updatedTriggered when shipping address is added or updated for a subscription.subscription_deletedSent when a subscription has been deletedinvoice_createdEvent 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_generatedEvent triggered when a new invoice is generated. In case of metered billing, this event is triggered when a "Pending" invoice is closed.invoice_updatedTriggered 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_deletedEvent triggered when an invoice is deleted.subscription_renewal_reminderSent before each subscription's renewal based on plan's periodtransaction_createdTriggered when a transaction is recordedtransaction_updatedTriggered 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_deletedTriggered when a transaction is deleted. payment_succeededSent when the payment is successfully collectedpayment_failedSent when attempt to charge customer's credit card failspayment_refundedSent when a payment refund is madepayment_initiatedSent when a payment is initiated via direct debitrefund_initiatedSent when a refund is initiated via direct debitcard_addedSent when a card is added for a customer.card_updatedSent when the card is updated for a customer.card_expiringSent when the customer's credit card is expiring soon. Sent 30 days before the expiry date.card_expiredSent when a card for a customer is expiredcard_deletedSent when a card is deleted for a customer
Show all values[+]
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
curl https://{site}.chargebee.com/api/v1/events/ev___test__5SK0bLNFRFuCIloNr \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v1/events/ev___test__5SK0bLNFRFuCIloNr \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"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}
always returned
Resource object representing event
Sample admin console URL
https://{site}.chargebee.com/admin-console/events/123x