chargebee 3.19.0 → 3.21.0

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+### v3.21.0 (2026-02-11)
+* * * 
+
+### 🚀 New Feature
+
+* Added webhook handler support. Refer to the [README.md](https://github.com/chargebee/chargebee-node/blob/master/README.md#handle-webhooks) for more details.
+
+### v3.20.0 (2026-02-06)
+* * *
+### New Attributes:
+- [`subscription_id`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/entitlement-override-object#subscription_id) has been added to [`EntitlementOverride`](https://apidocs.chargebee.com/docs/api/entitlement_overrides).
+- [`is_enabled`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/entitlement-override-object#is_enabled) has been added to [`EntitlementOverride`](https://apidocs.chargebee.com/docs/api/entitlement_overrides).
+- [`decommissioned`](https://apidocs.chargebee.com/docs/api/subscriptions/subscription-object#decommissioned) has been added to [`Subscription`](https://apidocs.chargebee.com/docs/api/subscriptions).
+
+
+### New Parameters:
+- [`omnichannel_subscription_item`](https://apidocs.chargebee.com/docs/api/omnichannel_subscriptions/list-omnichannel-subscriptions#omnichannel_subscription_item) has been added as query parameter to [`list_omnichannel_subscriptions`](https://apidocs.chargebee.com/docs/api/omnichannel_subscriptions/list-omnichannel-subscriptions) in [`OmnichannelSubscription`](https://apidocs.chargebee.com/docs/api/omnichannel_subscriptions).
+- [`entitlement_overrides.entity_id`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/upsert-or-remove-entitlement-overrides-for-a-subscription#entitlement_overrides_entity_id) has been added as request body parameter to [`upsert_or_remove_entitlement_overrides_for_a_subscription`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/upsert-or-remove-entitlement-overrides-for-a-subscription) in [`EntitlementOverride`](https://apidocs.chargebee.com/docs/api/entitlement_overrides).
+- [`entitlement_overrides.entity_type`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/upsert-or-remove-entitlement-overrides-for-a-subscription#entitlement_overrides_entity_type) has been added as request body parameter to [`upsert_or_remove_entitlement_overrides_for_a_subscription`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/upsert-or-remove-entitlement-overrides-for-a-subscription) in [`EntitlementOverride`](https://apidocs.chargebee.com/docs/api/entitlement_overrides).
+- [`entitlement_overrides.is_enabled`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/upsert-or-remove-entitlement-overrides-for-a-subscription#entitlement_overrides_is_enabled) has been added as request body parameter to [`upsert_or_remove_entitlement_overrides_for_a_subscription`](https://apidocs.chargebee.com/docs/api/entitlement_overrides/upsert-or-remove-entitlement-overrides-for-a-subscription) in [`EntitlementOverride`](https://apidocs.chargebee.com/docs/api/entitlement_overrides).
+- [`payment_method_save_policy`](https://apidocs.chargebee.com/docs/api/hosted_pages/collect-now#payment_method_save_policy) has been added as request body parameter to [`collect_now`](https://apidocs.chargebee.com/docs/api/hosted_pages/collect-now) in [`HostedPage`](https://apidocs.chargebee.com/docs/api/hosted_pages).
+- [`decommissioned`](https://apidocs.chargebee.com/docs/api/subscriptions/cancel-subscription-for-items#decommissioned) has been added as request body parameter to [`cancel_subscription_for_items`](https://apidocs.chargebee.com/docs/api/subscriptions/cancel-subscription-for-items) in [`Subscription`](https://apidocs.chargebee.com/docs/api/subscriptions).
+
+
+### Parameter Updates:
+- [`pricing_page`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-existing-subscription#pricing_page) has been changed from required to optional in [`create_pricing_page_for_existing_subscription`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions/create-pricing-page-for-existing-subscription) of [`PricingPageSession`](https://apidocs.chargebee.com/docs/api/pricing_page_sessions).
+
+
+### New Events:
+- [`payment_due_reminder`](https://apidocs.chargebee.com/docs/api/events/webhook/payment_due_reminder) has been added.
+
+
+### New Enums:
+- `charge` has been added as a new value enum `EntityType`.
+- `payment_due_reminder` has been added as a new value enum `EventType`.
+- `tempus` has been added as a new value enum `Gateway`.
+- `kakao_pay`, `naver_pay`, `revolut_pay`, and `cash_app_pay` have been added as new values enum `PaymentMethod`.
+- `always`, `ask`, and `never` have been added as new values enum `PaymentMethodSavePolicy`.
+- `kakao_pay`, `naver_pay`, `revolut_pay`, and `cash_app_pay` have been added as new values enum `PaymentMethodType`.
+- `kakao_pay`, `naver_pay`, `revolut_pay`, and `cash_app_pay` have been added as new values enum `Type`.
+- `accepted`, `rejected`, `message_acknowledgement`, `in_process`, `under_query`, `conditionally_accepted`, and `paid` have been added as new values to enum attribute [`einvoice.status`](https://apidocs.chargebee.com/docs/api/credit_notes/credit-note-object#einvoice_status) in [`CreditNote`](https://apidocs.chargebee.com/docs/api/credit_notes).
+- `accepted`, `rejected`, `message_acknowledgement`, `in_process`, `under_query`, `conditionally_accepted`, and `paid` have been added as new values to enum attribute [`status`](https://apidocs.chargebee.com/docs/api/einvoices/einvoice-object#status) in [`Einvoice`](https://apidocs.chargebee.com/docs/api/einvoices).
+- `accepted`, `rejected`, `message_acknowledgement`, `in_process`, `under_query`, `conditionally_accepted`, and `paid` have been added as new values to enum attribute [`einvoice.status`](https://apidocs.chargebee.com/docs/api/invoices/invoice-object#einvoice_status) in [`Invoice`](https://apidocs.chargebee.com/docs/api/invoices).
+- `kakao_pay`, `naver_pay`, `revolut_pay`, `cash_app_pay`, `wechat_pay`, and `alipay` have been added as new values to enum attribute [`payment_method_type`](https://apidocs.chargebee.com/docs/api/payment_intents/payment-intent-object#payment_method_type) in [`PaymentIntent`](https://apidocs.chargebee.com/docs/api/payment_intents).
+- `kakao_pay`, `naver_pay`, `revolut_pay`, `cash_app_pay`, `wechat_pay`, and `alipay` have been added as new values to enum attribute [`active_payment_attempt.payment_method_type`](https://apidocs.chargebee.com/docs/api/payment_intents/payment-intent-object#active_payment_attempt_payment_method_type) in [`PaymentIntent`](https://apidocs.chargebee.com/docs/api/payment_intents).
+- `kakao_pay`, `naver_pay`, `revolut_pay`, `cash_app_pay`, `wechat_pay`, and `alipay` have been added as new values to enum request body parameter `payment_method_type` in [`update_a_payment_intent`](https://apidocs.chargebee.com/docs/api/payment_intents/update-a-payment-intent) of [`PaymentIntent`](https://apidocs.chargebee.com/docs/api/payment_intents).
+- `kakao_pay`, `naver_pay`, `revolut_pay`, `cash_app_pay`, `wechat_pay`, and `alipay` have been added as new values to enum request body parameter `payment_method_type` in [`create_a_payment_intent`](https://apidocs.chargebee.com/docs/api/payment_intents/create-a-payment-intent) of [`PaymentIntent`](https://apidocs.chargebee.com/docs/api/payment_intents).
+
+
+
 ### v3.19.0 (2026-01-16)
 * * * 
 

package/README.md

@@ -148,6 +148,253 @@ const chargebeeSiteEU = new Chargebee({
 });
 ```
 
+### Handle webhooks
+
+Use the webhook handlers to parse and route webhook payloads from Chargebee with full TypeScript support.
+
+#### Quick Start: Using the instance `webhooks` handler
+
+The simplest way to handle webhooks is using the `webhooks` property on your initialized Chargebee client:
+
+```typescript
+import express from 'express';
+import Chargebee, {
+  AuthenticationError,
+  PayloadValidationError,
+  PayloadParseError,
+} from 'chargebee';
+
+const chargebee = new Chargebee({
+  site: '{{site}}',
+  apiKey: '{{api-key}}',
+});
+
+const app = express();
+app.use(express.json());
+
+// ⚠️ Register listeners once at startup, not inside request handlers
+chargebee.webhooks.on('subscription_created', async ({ event, response }) => {
+  console.log(`Subscription created: ${event.id}`);
+  const subscription = event.content.subscription;
+  console.log(`Customer: ${subscription.customer_id}`);
+  response?.status(200).send('OK');
+});
+
+chargebee.webhooks.on('error', (error, { response }) => {
+  if (error instanceof AuthenticationError) {
+    response?.status(401).send('Unauthorized');
+  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {
+    response?.status(400).send('Bad Request');
+  } else {
+    console.error('Webhook error:', error.message);
+    response?.status(500).send('Internal Server Error');
+  }
+});
+
+app.post('/chargebee/webhooks', async (req, res) => {
+  await chargebee.webhooks.handle({
+    body: req.body,
+    headers: req.headers,
+    request: req,
+    response: res,
+  });
+});
+
+app.listen(8080);
+```
+
+**Auto-configured Basic Auth:** The `webhooks` handler automatically configures Basic Auth validation if the following environment variables are set:
+
+- `CHARGEBEE_WEBHOOK_USERNAME` - The expected username
+- `CHARGEBEE_WEBHOOK_PASSWORD` - The expected password
+
+When both are present, incoming webhook requests will be validated against these credentials.
+
+#### Creating typed webhook handlers
+
+For more control or multiple webhook endpoints, use `chargebee.webhooks.createHandler()`:
+
+```typescript
+import express, { Request, Response } from 'express';
+import Chargebee, {
+  basicAuthValidator,
+  AuthenticationError,
+  PayloadValidationError,
+  PayloadParseError,
+} from 'chargebee';
+
+const chargebee = new Chargebee({
+  site: '{{site}}',
+  apiKey: '{{api-key}}',
+});
+
+const app = express();
+app.use(express.json());
+
+// Create a typed handler for Express
+const handler = chargebee.webhooks.createHandler<Request, Response>();
+
+// Optional: Add request validator (e.g., Basic Auth)
+handler.requestValidator = basicAuthValidator((username, password) => {
+  return username === 'admin' && password === 'secret';
+});
+
+// ⚠️ Register event listeners once at startup, not inside request handlers
+handler.on('subscription_created', async ({ event, response }) => {
+  console.log(`Subscription created: ${event.id}`);
+  const subscription = event.content.subscription;
+  console.log(`Customer: ${subscription.customer_id}`);
+  console.log(`Plan: ${subscription.plan_id}`);
+  response?.status(200).send('OK');
+});
+
+handler.on('payment_succeeded', async ({ event, response }) => {
+  console.log(`Payment succeeded: ${event.id}`);
+  const transaction = event.content.transaction;
+  const customer = event.content.customer;
+  console.log(`Amount: ${transaction.amount}, Customer: ${customer.email}`);
+  response?.status(200).send('OK');
+});
+
+handler.on('error', (error, { response }) => {
+  if (error instanceof AuthenticationError) {
+    response?.status(401).send('Unauthorized');
+  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {
+    response?.status(400).send('Bad Request');
+  } else {
+    console.error('Webhook error:', error.message);
+    response?.status(500).send('Internal Server Error');
+  }
+});
+
+app.post('/chargebee/webhooks', async (req, res) => {
+  await handler.handle({
+    body: req.body,
+    headers: req.headers,
+    request: req,
+    response: res,
+  });
+});
+
+app.listen(8080);
+```
+
+#### Low-level: Parse and handle events manually
+
+For more control, you can parse webhook events manually:
+
+```typescript
+import express from 'express';
+import Chargebee, { type WebhookEvent } from 'chargebee';
+
+const app = express();
+app.use(express.json());
+
+app.post('/chargebee/webhooks', async (req, res) => {
+  try {
+    const event = req.body as WebhookEvent;
+    
+    switch (event.event_type) {
+      case 'subscription_created':
+        // Access event content with proper typing
+        const subscription = event.content.subscription;
+        console.log('Subscription created:', subscription.id);
+        break;
+        
+      case 'payment_succeeded':
+        const transaction = event.content.transaction;
+        console.log('Payment succeeded:', transaction.amount);
+        break;
+        
+      default:
+        console.log('Unhandled event type:', event.event_type);
+    }
+    
+    res.status(200).send('OK');
+  } catch (err) {
+    console.error('Error processing webhook:', err);
+    res.status(500).send('Error processing webhook');
+  }
+});
+
+app.listen(8080);
+```
+
+#### Responding to Webhooks
+
+> ⚠️ **Important:** Always send an HTTP response from your webhook handlers. If you don't respond with a 2xx status, Chargebee will retry the webhook, potentially causing duplicate processing.
+
+**Respond with 200** to acknowledge receipt:
+
+```typescript
+handler.on('subscription_created', async ({ event, response }) => {
+  await provisionAccess(event.content.subscription);
+  response?.status(200).json({ received: true });
+});
+```
+
+**Respond with 5xx** so Chargebee retries on failure:
+
+```typescript
+handler.on('payment_succeeded', async ({ event, response }) => {
+  try {
+    await recordPayment(event.content.transaction);
+    response?.status(200).send('OK');
+  } catch (err) {
+    response?.status(500).json({ error: 'Processing failed' });
+  }
+});
+```
+
+**Access request context** (headers, middleware data):
+
+```typescript
+handler.on('customer_created', async ({ event, request, response }) => {
+  const tenantId = (request as any)?.tenant?.id;
+  await createCustomerForTenant(tenantId, event.content.customer);
+  response?.status(200).send('OK');
+});
+```
+
+#### Handling Unhandled Events and Errors
+
+The webhook handler provides specific error classes for different failure scenarios:
+
+- **`AuthenticationError`** - Authentication failed (missing/invalid credentials)
+- **`PayloadValidationError`** - Invalid webhook payload structure (missing required fields)
+- **`PayloadParseError`** - Failed to parse JSON body
+
+```typescript
+import {
+  AuthenticationError,
+  PayloadValidationError,
+  PayloadParseError,
+} from 'chargebee';
+
+// Handle events without registered listeners
+handler.on('unhandled_event', async ({ event, response }) => {
+  console.log(`Unhandled: ${event.event_type}`);
+  response?.status(200).send('OK');
+});
+
+// Handle errors with appropriate HTTP status codes
+handler.on('error', (error, { response }) => {
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', error.message);
+    response?.status(401).send('Unauthorized');
+  } else if (error instanceof PayloadValidationError) {
+    console.error('Invalid payload:', error.message);
+    response?.status(400).send('Bad Request');
+  } else if (error instanceof PayloadParseError) {
+    console.error('Failed to parse JSON:', error.message);
+    response?.status(400).send('Bad Request');
+  } else {
+    console.error('Unknown error:', error.message);
+    response?.status(500).send('Internal Server Error');
+  }
+});
+```
+
 ### Processing Webhooks - API Version Check
 
 An attribute `api_version` is added to the [Event](https://apidocs.chargebee.com/docs/api/events) resource, which indicates the API version based on which the event content is structured. In your webhook servers, ensure this `api_version` is the same as the [API version](https://apidocs.chargebee.com/docs/api#versions) used by your webhook server's client library.
@@ -227,35 +474,15 @@ To improve type safety and gain better autocompletion when working with webhooks
 import Chargebee, { WebhookEventType, WebhookEvent } from "chargebee";
 
 const result = await chargebeeInstance.event.retrieve("{event-id}");
-const subscriptionActivatedEvent: WebhookEvent<typeof WebhookEventType.SubscriptionActivated> = result.event;
+const subscriptionActivatedEvent: WebhookEvent<WebhookEventType.SubscriptionActivated> = result.event;
 const subscription = subscriptionActivatedEvent.content.subscription;
 ```
 
-You can also use `WebhookEventType` in switch statements for runtime event handling:
-
-```ts
-import { WebhookEventType, WebhookEvent } from "chargebee";
-
-function handleWebhook(event: WebhookEvent) {
-  switch (event.event_type) {
-    case WebhookEventType.SubscriptionCreated:
-      console.log("Subscription created:", event.content.subscription?.id);
-      break;
-    case WebhookEventType.PaymentSucceeded:
-      console.log("Payment succeeded:", event.content.transaction?.id);
-      break;
-    default:
-      console.log("Unhandled event:", event.event_type);
-  }
-}
-```
-
 #### Notes
 
 * `WebhookEvent<T>` provides type hinting for the event payload, making it easier to work with specific event structures.
-* Use `WebhookEventType` to specify the exact event type (e.g., `SubscriptionCreated`, `InvoiceGenerated`, etc.).
-* `WebhookEventType` is available at runtime, so you can use it in switch statements and comparisons.
-* `WebhookContentType` is deprecated but still available for backward compatibility.
+* Use the `WebhookEventType` to specify the exact event type (e.g., `SubscriptionCreated`, `InvoiceGenerated`, etc.).
+* This approach ensures you get proper IntelliSense and compile-time checks when accessing event fields.
 
 ### Custom HTTP Client
 

package/cjs/chargebee.cjs.js

@@ -2,12 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const createChargebee_js_1 = require("./createChargebee.js");
 const FetchClient_js_1 = require("./net/FetchClient.js");
-const eventType_js_1 = require("./resources/webhook/eventType.js");
+const handler_js_1 = require("./resources/webhook/handler.js");
+const auth_js_1 = require("./resources/webhook/auth.js");
 const httpClient = new FetchClient_js_1.FetchHttpClient();
 const Chargebee = (0, createChargebee_js_1.CreateChargebee)(httpClient);
 module.exports = Chargebee;
 module.exports.Chargebee = Chargebee;
 module.exports.default = Chargebee;
-// Export webhook event types
-module.exports.WebhookEventType = eventType_js_1.WebhookEventType;
-module.exports.WebhookContentType = eventType_js_1.WebhookContentType;
+// Export webhook utilities
+module.exports.WebhookEventType = handler_js_1.WebhookEventType;
+module.exports.WebhookContentType = handler_js_1.WebhookContentType;
+module.exports.basicAuthValidator = auth_js_1.basicAuthValidator;
+// Export webhook error classes
+module.exports.WebhookError = handler_js_1.WebhookError;
+module.exports.WebhookAuthenticationError = handler_js_1.WebhookAuthenticationError;
+module.exports.WebhookPayloadValidationError = handler_js_1.WebhookPayloadValidationError;
+module.exports.WebhookPayloadParseError = handler_js_1.WebhookPayloadParseError;

package/cjs/createChargebee.js

@@ -6,6 +6,7 @@ const environment_js_1 = require("./environment.js");
 const api_endpoints_js_1 = require("./resources/api_endpoints.js");
 const util_js_1 = require("./util.js");
 const asyncApiSupport_js_1 = require("./asyncApiSupport.js");
+const handler_js_1 = require("./resources/webhook/handler.js");
 const CreateChargebee = (httpClient) => {
     const Chargebee = function (conf) {
         this._env = Object.assign({}, environment_js_1.Environment);
@@ -15,6 +16,14 @@ const CreateChargebee = (httpClient) => {
             conf.httpClient != null ? conf.httpClient : httpClient;
         this._buildResources();
         this._endpoints = api_endpoints_js_1.Endpoints;
+        // Initialize webhooks handler with auto-configured Basic Auth (if env vars are set)
+        const handler = (0, handler_js_1.createDefaultHandler)();
+        // Create webhooks namespace with handler methods + createHandler factory
+        this.webhooks = Object.assign(handler, {
+            createHandler(options) {
+                return new handler_js_1.WebhookHandler(options);
+            },
+        });
     };
     Chargebee.prototype = {
         _createApiFunc(apiCall, env) {

package/cjs/environment.js

@@ -11,7 +11,7 @@ exports.Environment = {
     hostSuffix: '.chargebee.com',
     apiPath: '/api/v2',
     timeout: DEFAULT_TIME_OUT,
-    clientVersion: 'v3.19.0',
+    clientVersion: 'v3.21.0',
     port: DEFAULT_PORT,
     timemachineWaitInMillis: DEFAULT_TIME_MACHINE_WAIT,
     exportWaitInMillis: DEFAULT_EXPORT_WAIT,

package/cjs/resources/webhook/auth.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.basicAuthValidator = void 0;
+const errors_js_1 = require("./errors.js");
+/**
+ * Creates a Basic Auth validator for webhook requests.
+ * Parses the Authorization header and validates credentials.
+ *
+ * @param validateCredentials - Function to validate username/password.
+ *   Can be sync or async (e.g., for database lookups).
+ * @returns A request validator function for use with WebhookHandler
+ *
+ * @throws {WebhookAuthenticationError} When authentication fails
+ *
+ * @example
+ * // Simple sync validation
+ * const validator = basicAuthValidator((u, p) => u === 'admin' && p === 'secret');
+ *
+ * @example
+ * // Async validation (e.g., database lookup)
+ * const validator = basicAuthValidator(async (u, p) => {
+ *   const user = await db.findUser(u);
+ *   return user && await bcrypt.compare(p, user.passwordHash);
+ * });
+ */
+const basicAuthValidator = (validateCredentials) => {
+    return async (headers) => {
+        const authHeader = headers['authorization'] || headers['Authorization'];
+        if (!authHeader) {
+            throw new errors_js_1.WebhookAuthenticationError('Missing authorization header');
+        }
+        const authStr = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+        if (!authStr) {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid authorization header');
+        }
+        const parts = authStr.split(' ');
+        if (parts.length !== 2 || parts[0] !== 'Basic') {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid authorization header format');
+        }
+        const decoded = Buffer.from(parts[1], 'base64').toString();
+        const separatorIndex = decoded.indexOf(':');
+        if (separatorIndex === -1) {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid credentials format');
+        }
+        const username = decoded.substring(0, separatorIndex);
+        const password = decoded.substring(separatorIndex + 1);
+        const isValid = await validateCredentials(username, password);
+        if (!isValid) {
+            throw new errors_js_1.WebhookAuthenticationError('Invalid credentials');
+        }
+    };
+};
+exports.basicAuthValidator = basicAuthValidator;

package/cjs/resources/webhook/content.js

@@ -0,0 +1,4 @@
+"use strict";
+///<reference path='../../../types/index.d.ts'/>
+Object.defineProperty(exports, "__esModule", { value: true });
+const eventType_js_1 = require("./eventType.js");

package/cjs/resources/webhook/errors.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookPayloadParseError = exports.WebhookPayloadValidationError = exports.WebhookAuthenticationError = exports.WebhookError = void 0;
+/**
+ * Base class for all webhook-related errors.
+ * Extends the standard Error class with proper stack trace support.
+ */
+class WebhookError extends Error {
+    constructor(message) {
+        var _a;
+        super(message);
+        this.name = 'WebhookError';
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        (_a = Error.captureStackTrace) === null || _a === void 0 ? void 0 : _a.call(Error, this, this.constructor);
+    }
+}
+exports.WebhookError = WebhookError;
+/**
+ * Authentication error thrown when webhook request authentication fails.
+ *
+ * Common scenarios:
+ * - Missing authorization header
+ * - Invalid authorization header format
+ * - Invalid credentials
+ *
+ * Typically maps to HTTP 401 Unauthorized.
+ *
+ * @example
+ * ```typescript
+ * handler.on('error', (error, { response }) => {
+ *   if (error instanceof WebhookAuthenticationError) {
+ *     response?.status(401).json({ error: 'Unauthorized' });
+ *   }
+ * });
+ * ```
+ */
+class WebhookAuthenticationError extends WebhookError {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookAuthenticationError';
+    }
+}
+exports.WebhookAuthenticationError = WebhookAuthenticationError;
+/**
+ * Payload validation error thrown when the webhook payload structure is invalid.
+ *
+ * Common scenarios:
+ * - Missing required fields (event_type, id)
+ * - Invalid field types
+ * - Malformed payload structure
+ *
+ * Typically maps to HTTP 400 Bad Request.
+ *
+ * @example
+ * ```typescript
+ * handler.on('error', (error, { response }) => {
+ *   if (error instanceof WebhookPayloadValidationError) {
+ *     response?.status(400).json({ error: 'Bad Request', message: error.message });
+ *   }
+ * });
+ * ```
+ */
+class WebhookPayloadValidationError extends WebhookError {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookPayloadValidationError';
+    }
+}
+exports.WebhookPayloadValidationError = WebhookPayloadValidationError;
+/**
+ * JSON parsing error thrown when the webhook body cannot be parsed as JSON.
+ *
+ * Includes the raw body that failed to parse (if available) for debugging.
+ *
+ * Typically maps to HTTP 400 Bad Request.
+ *
+ * @example
+ * ```typescript
+ * handler.on('error', (error, { response }) => {
+ *   if (error instanceof WebhookPayloadParseError) {
+ *     console.error('Failed to parse:', error.rawBody);
+ *     response?.status(400).json({ error: 'Invalid JSON' });
+ *   }
+ * });
+ * ```
+ */
+class WebhookPayloadParseError extends WebhookError {
+    constructor(message, rawBody) {
+        super(message);
+        this.rawBody = rawBody;
+        this.name = 'WebhookPayloadParseError';
+    }
+}
+exports.WebhookPayloadParseError = WebhookPayloadParseError;

package/cjs/resources/webhook/eventType.js

@@ -125,6 +125,7 @@ var WebhookEventType;
     WebhookEventType["OrderResent"] = "order_resent";
     WebhookEventType["OrderReturned"] = "order_returned";
     WebhookEventType["OrderUpdated"] = "order_updated";
+    WebhookEventType["PaymentDueReminder"] = "payment_due_reminder";
     WebhookEventType["PaymentFailed"] = "payment_failed";
     WebhookEventType["PaymentInitiated"] = "payment_initiated";
     WebhookEventType["PaymentIntentCreated"] = "payment_intent_created";
@@ -233,6 +234,16 @@ var WebhookEventType;
     WebhookEventType["VoucherExpired"] = "voucher_expired";
 })(WebhookEventType || (exports.WebhookEventType = WebhookEventType = {}));
 /**
- * @deprecated Use WebhookEventType instead.
+ * @deprecated Renamed to `WebhookEventType` for clarity. Use `WebhookEventType` instead.
+ * This alias will be removed in the next major version.
+ *
+ * @example
+ * // Before (deprecated)
+ * import { WebhookContentType } from 'chargebee';
+ * if (event.event_type === WebhookContentType.SubscriptionCreated) { ... }
+ *
+ * // After (recommended)
+ * import { WebhookEventType } from 'chargebee';
+ * if (event.event_type === WebhookEventType.SubscriptionCreated) { ... }
  */
 exports.WebhookContentType = WebhookEventType;