# Webhook endpoints

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


A webhook endpoint receives real-time notifications from your Chargebee site when specific events occur, such as invoice generation, payment failures, or subscription updates. It allows your application, server, or third-party service to automatically respond to these changes, eliminating the need for manual checks or polling the API. Each webhook endpoint includes details such as a unique ID, target URL, list of subscribed events, and status. You can manage webhook endpoints using the Chargebee dashboard or the API.

**Note** You can create up to five webhook endpoints per site.

## Sample Webhook endpoint

```json
{
  "id": "whv2_198PKVUX26UX9IvR",
  "name": "Chargebee Notification",
  "api_version": "v2",
  "url": "https://{host}.com",
  "primary_url": true,
  "send_card_resource": false,
  "disabled": false
}
```

## Webhook endpoints attributes

## Input Parameters

- `id` (required, string, max chars=40)
  A unique identifier for the webhook.

- `name` (required, string, max chars=50)
  The name assigned to the webhook.

- `url` (required, string, max chars=512)
  The full URL of the webhook endpoint.

- `send_card_resource` (optional, boolean, default=false)
  Controls whether card-related resources are included in the webhook payload. Card details are always masked.

- `disabled` (required, boolean, default=false)
  Indicates whether the webhook endpoint is disabled. If `true` , the endpoint is disabled; if `false` , it is enabled.

- `primary_url` (required, boolean, default=false)
  Indicates whether this is the primary webhook endpoint. If only one endpoint exists, it is considered primary by default.

- `api_version` (required, enumerated string, default=v2)
  Specifies the API version used to format the webhook payload. Make sure this version matches the client library version used by your webhook server.
  Possible enum values:
    - `v1`
      If selected, the webhook payload includes only attributes from API v1 resources.
    - `v2`
      If selected, the webhook payload includes only attributes from API v2 resources.

- `chargebee_response_schema_type` (optional, enumerated string)
  Indicates the response schema used in the webhook payload, based on the product catalog version configured for the site.
  
  **Note** This field is only applicable if the site is in [`compat`](https://www.chargebee.com/docs/billing/1.0/product-catalog/product-catalog-coexistence-ui-changes) mode.
  Possible enum values:
    - `plans_addons`
      The webhook payload follows the [Product Catalog 1.0](https://www.chargebee.com/docs/billing/1.0/product-catalog/product-catalog) schema and uses the [Plans](/docs/api/v2/pcv-1/plans) and [Addons](/docs/api/v2/pcv-1/addons) model.
    - `items`
      The webhook payload follows the [Product Catalog 2.0](https://www.chargebee.com/docs/billing/2.0/product-catalog/product-catalog) schema and uses the [Items API model](/docs/api/items) .
    - `compat`
      The webhook payload uses a schema compatible with both Product Catalog 1.0 and 2.0. This is applicable only to sites automatically upgraded to Product Catalog 2.0.

- `enabled_events` (optional, enumerated string)
  The types of events that trigger this webhook. For a complete list, see [event types](/docs/api/v2/pcv-1/webhook_endpoints) .
  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 an addon is created.
    - `addon_updated`
      Sent when an addon is changed.
    - `addon_deleted`
      Sent when an 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 promotional credits are added for a customer
    - `promotional_credits_deducted`
      Sent when promotional credits are deducted for a customer
    - `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 its 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`
      Event triggered when the option "Notify and wait to close invoices" is enabled, and the 'Pending' invoice is updated.
    - `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 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_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
    - `einvoice_created`
      Triggered when an e-invoice is created for an invoice or credit note.
    - `einvoice_updated`
      Triggered when an e-invoice is updated (for example when its status or provider responses change).
    - `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 an attempt to charge the customer's credit card fails
    - `dunning_updated`
      Sent when dunning is paused for an invoice
    - `retry_segment_assigned`
      Triggered when an invoice's dunning starts and it matches a retry segment, including the default segment. The invoice is retried under the settings locked in the `invoice_retry_context`.
    - `payment_refunded`
      Sent when a payment refund is made
    - `refund_failed`
      Triggered when a refund attempt fails at the gateway.
    - `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 an authorization transaction is created.
    - `authorization_voided`
      Triggered when an 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 is 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 an order is created
    - `order_updated`
      Triggered when an order is updated
    - `order_cancelled`
      Triggered when an order is cancelled
    - `order_delivered`
      Triggered when an order is marked as delivered
    - `order_returned`
      Triggered when an order is marked as returned
    - `order_ready_to_process`
      Triggered when an order reaches its order date
    - `order_ready_to_ship`
      Triggered when an order reaches its shipping date
    - `order_deleted`
      Triggered when an order is deleted
    - `order_resent`
      Triggered when an order is resent
    - `quote_created`
      Triggered when a quote is created
    - `quote_updated`
      Triggered when a quote is updated
    - `quote_deleted`
      Triggered when a 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 payment voucher creation fails
    - `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.
    - `chargeback_initiated`
      Triggered when a chargeback is raised against a payment.
    - `chargeback_won`
      Triggered when a chargeback is resolved in the merchant's favor.
    - `chargeback_lost`
      Triggered when a chargeback is resolved in the cardholder's favor.

