Package com.chargebee.v4.webhook

Class WebhookEventHandler

java.lang.Object
com.chargebee.v4.webhook.WebhookEventHandler
public class WebhookEventHandler extends Object
Central handler for processing Chargebee webhook events.

This class provides a fluent API for registering event callbacks and processing incoming webhook notifications. It handles optional Basic Auth verification, event parsing, and routing to appropriate handlers.

Quick Start:

 // Create the handler
 WebhookEventHandler handler = WebhookEventHandler.create();
 
 // Register callbacks for specific event types (class is auto-resolved via type witness)
 handler.<CustomerCreatedEvent>on(Event.EventType.CUSTOMER_CREATED, event -> {
     Customer customer = event.getContent().getCustomer();
     System.out.println("Customer created: " + customer.getEmail());
     return WebhookResult.success(event.getEventType(), event.getId());
 });
 
 handler.<SubscriptionCancelledEvent>on(Event.EventType.SUBSCRIPTION_CANCELLED, event -> {
     Subscription sub = event.getContent().getSubscription();
     System.out.println("Subscription cancelled: " + sub.getId());
     return WebhookResult.success(event.getEventType(), event.getId());
 });
 
 // Process incoming webhook (in your controller)
 WebhookResult result = handler.handleWebhook(requestBody);

With Basic Auth (Optional):

 WebhookEventHandler handler = WebhookEventHandler.builder()
     .basicAuth("username", "password")
     .fallbackCallback((event, eventType, rawPayload) -> {
         System.out.println("Unhandled event: " + eventType);
         return WebhookResult.unhandled(eventType, event.getId());
     })
     .build();
 
 // Process with auth verification
 WebhookResult result = handler.handleWebhook(requestBody, authorizationHeader);

Common Event Types:

  • customer_created, customer_changed, customer_deleted
  • subscription_created, subscription_activated, subscription_cancelled, subscription_renewed
  • invoice_generated, invoice_updated, invoice_deleted
  • payment_succeeded, payment_failed, payment_refunded
  • card_added, card_updated, card_expired
See Also:

  • Method Details

    • create

      public static WebhookEventHandler create()
      Creates a simple WebhookEventHandler without authentication.
      Returns:
      A new WebhookEventHandler instance

    • builder

      public static WebhookEventHandler.Builder builder()
      Creates a new builder for WebhookEventHandler.
      Returns:
      A new Builder instance

    • on

      public <T> WebhookEventHandler on(Event.EventType eventType, WebhookEventCallback<T> callback)
      Registers a callback for a specific event type. The event class is automatically derived from the event type.

      Usage with type witness:

       handler.<CustomerCreatedEvent>on(Event.EventType.CUSTOMER_CREATED, event -> {
     Customer customer = event.getContent().getCustomer();
     return WebhookResult.success(event.getEventType(), event.getId());
 });
      Type Parameters:
      T - The type of the event class
      Parameters:
      eventType - The event type enum value (e.g., Event.EventType.CUSTOMER_CREATED)
      callback - The callback to invoke when this event type is received
      Returns:
      This handler for method chaining
      Throws:
      WebhookEventHandler.WebhookException - if the event class cannot be found

    • handleWebhook

      public WebhookResult handleWebhook(String payload)
      Processes an incoming webhook request without authentication.
      Parameters:
      payload - The raw request body (JSON)
      Returns:
      WebhookResult from the callback
      Throws:
      WebhookEventHandler.WebhookException - if processing fails

    • handleWebhook

      public WebhookResult handleWebhook(String payload, String authorizationHeader)
      Processes an incoming webhook request with optional authentication.

      This method:

      1. Verifies Basic Auth credentials (if configured)
      2. Parses the payload to determine event type
      3. Parses the payload to the typed event class
      4. Routes to the appropriate registered callback or fallback
      5. Returns the WebhookResult from the callback
      Parameters:
      payload - The raw request body (JSON)
      authorizationHeader - The Authorization header value (can be null)
      Returns:
      WebhookResult from the callback
      Throws:
      WebhookEventHandler.WebhookException - if processing fails

    • hasCallback

      public boolean hasCallback(String eventType)
      Checks if a callback is registered for the given event type.
      Parameters:
      eventType - The event type to check
      Returns:
      true if a callback is registered

    • getRegisteredCallbackCount

      public int getRegisteredCallbackCount()
      Returns the number of registered callbacks.
      Returns:
      The number of registered callbacks