Settings
API Version
Product Catalog
Library

Webhook endpoints

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 }

API Index URL GET

https://{site}.chargebee.com/api/v2/webhook_endpoints

Model Class

 

      Webhook endpoint attributes
      
 
id
 

      string, max chars=40
 A unique identifier for the webhook. 
 
 
name
 

      string, max chars=50
 The name assigned to the webhook. 
 
 
url
 

      string, max chars=250
 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
 

      boolean, default=false
 Indicates whether the webhook endpoint is disabled. If true, the endpoint is disabled; if false, it is enabled. 
 
 
primary_url
 

      boolean, default=false
 Indicates whether this is the primary webhook endpoint. If only one endpoint exists, it is considered primary by default. 
 
 
api_version
 

      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 values are
 
 
v1If selected, the webhook payload includes only attributes from API v1 resources.v2If selected, the webhook payload includes only attributes from API v2 resources.
 
 Show all values[+]
 
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 mode.
 
 
Possible values are
 
 
plans_addonsThe webhook payload follows the Product Catalog 1.0 schema and uses the Plans and Addons model.itemsThe webhook payload follows the Product Catalog 2.0 schema and uses the Items API model.compatThe 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.
 
 Show all values[+]
 
enabled_events
 

      optional, list of string
 The types of events that trigger this webhook. For a complete list, see event types. 
 
Possible values are
 
 
coupon_createdcoupon_updatedcoupon_deletedcoupon_set_created
 
 Show all values[+]
 
 
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.
    
 
 
id id
 

          string, max chars=40
 A unique identifier for the webhook. 
 
name name
 

          string, max chars=50
 The name assigned to the webhook. 
 
url url
 

          string, max chars=250
 The full URL of the webhook endpoint. 
 
send_card_resource send_card_resource
 

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

          boolean, default=false
 Indicates whether the webhook endpoint is disabled. If true, the endpoint is disabled; if false, it is enabled. 
 
primary_url primary_url
 

          boolean, default=false
 Indicates whether this is the primary webhook endpoint. If only one endpoint exists, it is considered primary by default. 
 
api_version api_version
 

          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 values are
 
 
v1If selected, the webhook payload includes only attributes from API v1 resources.v2If selected, the webhook payload includes only attributes from API v2 resources.
 
 Show all values[+]
chargebee_response_schema_type 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 mode.
 
 
Possible values are
 
 
plans_addonsThe webhook payload follows the Product Catalog 1.0 schema and uses the Plans and Addons model.itemsThe webhook payload follows the Product Catalog 2.0 schema and uses the Items API model.compatThe 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.
 
 Show all values[+]
enabled_events enabled_events
 

          optional, list of string
 The types of events that trigger this webhook. For a complete list, see event types. 
 
Possible values are
 
 
coupon_createdcoupon_updatedcoupon_deletedcoupon_set_created
 
 Show all values[+]
 
 
Consent Fields for Webhook endpoint
 
 
Custom Fields for Webhook endpoint
 
  

      Create a webhook endpoint
      
 
Idempotency Supported
 
 
Create a new webhook endpoint on your Chargebee Site.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/webhook_endpoints \
     -u {site_api_key}:\
     -d name="Chargebee Notification" \
     -d api_version="V2" \
     -d url="https://{host}.com" \
     -d primary_url=true \
     -d disabled=false \
     -d send_card_resource=false
 

      copy
      
Click to Copy
 
Creates a webhook endpoint.
 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "webhook_endpoint": {
        "id": "whv2_198PKVUX26UX9IvR",
        "name": "Chargebee Notification",
        "api_version": "v2",
        "url": "https://{host}.com",
        "primary_url": true,
        "send_card_resource": false,
        "disabled": false
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/webhook_endpoints
    
 
Method
 
 
Input Parameters
 
  
 
name[]
 

      required, string, max chars=50 
 A name to identify the webhook endpoint. 
 
api_version[]
 

      optional, enumerated string, default=v2 
 The API version used to format the webhook payload. Ensure this version matches the client library used by your webhook server 
Possible values are
 
 
v1If selected, the payload includes only attributes from API v1 resources.v2If selected, the payload includes only attributes from API v2 resources.
 
 Show all values[+]
 
url[]
 

      required, string, max chars=250 
 The target URL where webhook notifications will be sent.  
Note
 Only URL ports 80, 443, 8080, or 8443 are  allowed.
 
 
primary_url[]
 

      optional, boolean, default=false 
 Indicates whether this webhook is marked as the primary endpoint. If only one exists, it is primary by default. 
 
disabled[]
 

      optional, boolean, default=false 
 Indicates whether the webhook endpoint is disabled. Set to true to disable the endpoint, set to false to enable the endpoint. 
 
basic_auth_password[]
 

      optional, string, max chars=250 
 The password used for basic authentication to secure webhook delivery. 
 
basic_auth_username[]
 

      optional, string, max chars=250 
 Username for basic authentication used to secure webhook delivery. 
 
send_card_resource[]
 

      optional, boolean, default=false 
 Controls whether card-related resources are included in the webhook payload. Card details are always masked. 
 
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 mode.
 
Possible values are
 
 
plans_addonsThe webhook payload follows the Product Catalog 1.0 schema and uses the Plans and Addons model.itemsThe webhook payload follows the Product Catalog 2.0 schema and uses the Items API model.compatThe 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.
 
 Show all values[+]
 
enabled_events[[0..n]][0..n]
 

      optional, list of string 
 A list of event types that trigger this webhook. 
Note
 If this field is left empty, the webhook will enable all event types by default.
 
Possible values are
 
 
coupon_createdcoupon_updatedcoupon_deletedcoupon_set_created
 
 Show all values[+]
 
 
    
 
Returns
 
webhook_endpoint  webhook_endpoint
 

      always returned 
 Resource object representing webhook_endpoint
 
Sample admin console URL
 

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

      Update webhook endpoint
      
 
Idempotency Supported
 
 
Updates the configuration of an existing webhook endpoint using its unique identifier. You can use this API to change properties such as the name, URL, subscribed events, authentication credentials, or API version. This is useful when rotating endpoints, updating destination URLs, or modifying which events your system listens to.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/webhook_endpoints/whv2_198PKVUX26UX9IvR \
     -u {site_api_key}:\
     -d name="Notify Subscriptions" \
     -d url="https://{new-host}.com" \
     -d primary_url=true
 

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "webhook_endpoint": {
        "id": "whv2_198PKVUX26UX9IvR",
        "name": "Notify Subscription",
        "api_version": "v2",
        "enabled_events": [
            "subscription_created",
            {..}
        ],
        "url": "https://{host}.com",
        "primary_url": true,
        "send_card_resource": false,
        "disabled": false
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/webhook_endpoints/{webhook-endpoint-id}
    
 
Method
 
 
Input Parameters
 
  
 
name[]
 

      optional, string, max chars=50 
 A name to identify the webhook endpoint. 
 
api_version[]
 

      optional, enumerated string, default=v2 
 The API version used to format the webhook payload. Ensure this version matches the client library used by your webhook server. 
Possible values are
 
 
v1If selected, the payload includes only attributes from API v1 resources.v2If selected, the payload includes only attributes from API v2 resources.
 
 Show all values[+]
 
url[]
 

      optional, string, max chars=250 
 The target URL where webhook notifications will be sent.  
Note
 Only URL ports 80, 443, 8080, or 8443 are  allowed.
 
 
primary_url[]
 

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

      optional, boolean, default=false 
 Specifies whether card-related resources should be included in the webhook payload. 
 
basic_auth_password[]
 

      optional, string, max chars=250 
 The password used for basic authentication to secure webhook delivery. 
 
basic_auth_username[]
 

      optional, string, max chars=250 
 Username for basic authentication used to secure webhook delivery. 
 
disabled[]
 

      optional, boolean, default=false 
 Indicates whether the webhook endpoint is disabled. Set to true to disable the endpoint, set to false to enable the endpoint. 
 
enabled_events[[0..n]][0..n]
 

      optional, list of string 
 A list of event types that trigger this webhook. 
Note
 If this field is left empty, the webhook will enable all event types by default.
 
Possible values are
 
 
coupon_createdcoupon_updatedcoupon_deletedcoupon_set_created
 
 Show all values[+]
 
 
    
 
Returns
 
webhook_endpoint  webhook_endpoint
 

      always returned 
 Resource object representing webhook_endpoint
 
Sample admin console URL
 

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

      Retrieve a webhook endpoint
      
  
 
Retrieves the details of a specific webhook endpoint using its unique identifier. Use this API to inspect an endpoint’s configuration, such as the target URL, subscribed events, and authentication settings.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/webhook_endpoints/whv2_198PKVUX26UX9IvR \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
Retrieve a webhook endpoint.
 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "webhook_endpoint": {
        "id": "whv2_198PKVUX26UX9IvR",
        "name": "Notify Subscription",
        "api_version": "v2",
        "enabled_events": [
            "subscription_created",
            {..}
        ],
        "url": "https://{host}.com",
        "primary_url": true,
        "send_card_resource": false,
        "disabled": false
    }
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/webhook_endpoints/{webhook-endpoint-id}
    
 
Method
 
  
   
 
    
 
Returns
 
webhook_endpoint  webhook_endpoint
 

      always returned 
 Resource object representing webhook_endpoint
 
Sample admin console URL
 

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

      Delete a webhook endpoint
      
 
Idempotency Supported
 
 
Deletes a webhook endpoint using its unique identifier. Use this API to remove obsolete or inactive webhook endpoints from your Chargebee site. Deleting an endpoint ensures it no longer receives event notifications.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/webhook_endpoints/whv2_198PKVUX26UX9IvR/delete \
     -X POST  \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
Delete a webhook endpoint.
 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "webhook_endpoint": {
        "id": "whv2_198PKVUX26UX9IvR",
        "name": "Notify Subscription",
        "api_version": "v2",
        "enabled_events": [
            "subscription_created",
            {..}
        ],
        "url": "https://{host}.com",
        "primary_url": true,
        "send_card_resource": false,
        "disabled": false
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/webhook_endpoints/{webhook-endpoint-id}/delete
    
 
Method
 
  
   
 
    
 
Returns
 
webhook_endpoint  webhook_endpoint
 

      always returned 
 Resource object representing webhook_endpoint
 
Sample admin console URL
 

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

      List webhook endpoints
      
  
 
Retrieves all webhook endpoints configured on your Chargebee site. The response includes each endpoint’s ID, name, and target URL. Use this API to view, audit, or manage the list of webhook endpoints currently active or configured in your site.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/webhook_endpoints \
     -G  \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
List webhook endpoints.
 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "list": [
        {
            "webhook_endpoint": {
                "id": "whv2_198PKVUX26UX9IvR",
                "name": "Notify Subscription",
                "api_version": "v2",
                "enabled_events": [
                    "subscription_created",
                    {..}
                ],
                "url": "https://{host}.com",
                "primary_url": true,
                "send_card_resource": false,
                "disabled": false
            }
        },
        {..}
    ]
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/webhook_endpoints
    
 
Method
 
 
Input Parameters
 
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. 
   
 
    
 
Returns
 
webhook_endpoint  webhook_endpoint
 

      always returned 
 Resource object representing webhook_endpoint
next_offset  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`.
 
Sample admin console URL
 

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