Webhook endpoints

API Version

Product Catalog

Library

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

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

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

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

enabled_events

optional, list of string
The types of events that trigger this webhook. For a complete list, see event types.

Possible values are

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

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

enabled_events

optional, list of string
The types of events that trigger this webhook. For a complete list, see event types.

Possible values are

Try in API Explorer

Create a new webhook endpoint on your Chargebee Site.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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.

200:

STATUS

Sample Response [ JSON ]

{
    "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

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

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

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

webhook_endpoint

always returned
Resource object representing webhook_endpoint

Try in API Explorer

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.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

200:

STATUS

Sample Response [ JSON ]

{
    "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}

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

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

webhook_endpoint

always returned
Resource object representing webhook_endpoint

Try in API Explorer

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.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

Retrieve a webhook endpoint.

200:

STATUS

Sample Response [ JSON ]

{
    "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}

webhook_endpoint

always returned
Resource object representing webhook_endpoint

Try in API Explorer

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.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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.

200:

STATUS

Sample Response [ JSON ]

{
    "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

webhook_endpoint

always returned
Resource object representing webhook_endpoint

Try in API Explorer

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.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

List webhook endpoints.

200:

STATUS

Sample Response [ JSON ]

{
    "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

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.

webhook_endpoint

always returned
Resource object representing webhook_endpoint

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 webhook endpoint [ JSON ]

API Index URL

Model Class

Webhook endpoint attributes

Consent Fields for Webhook endpoint

Custom Fields for Webhook endpoint

Create a webhook endpoint ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update webhook endpoint ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a webhook endpoint ¶

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

Delete a webhook endpoint ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List webhook endpoints ¶

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