Feat/webhook parser

CHANGELOG.md

@@ -1,3 +1,9 @@
+### v3.40.0-beta.1 (2025-11-18)
+***
+
+### New Enhancement:
+* Added a webhook parser to automatically convert event JSON payloads into Chargebee objects.
+
 ### v3.39.0 ( 2025-10-28)
 * * * 
 

README.md

@@ -253,8 +253,109 @@ func main() {
 ```
 `IsIdempotencyReplayed()` method can be accessed to differentiate between original and replayed requests.
 
+### Handle webhooks
 
+Use the `webhook` package to parse and route webhook payloads from Chargebee.
 
+High-level: route events with callbacks using `WebhookHandler`:
+
+```go
+package main
+
+import (
+	"log"
+	"net/http"
+
+	"github.com/chargebee/chargebee-go/v3/webhook"
+)
+
+func main() {
+	handler := &webhook.WebhookHandler{
+		// Optional: protect endpoint (e.g., Basic Auth)
+		RequestValidator: webhook.BasicAuthValidator(func(user, pass string) bool {
+			return user == "admin" && pass == "secret"
+		}),
+		OnError: webhook.BasicAuthErrorHandler, // Optional: standard auth error responses
+
+		// Register only the events you care about
+		OnSubscriptionCreated: func(e webhook.SubscriptionCreatedEvent) error {
+			log.Printf("Subscription created event %s", e.Id)
+			return nil
+		},
+		OnPaymentSucceeded: func(e webhook.PaymentSucceededEvent) error {
+			log.Printf("Payment succeeded for customer: %v", e.Content.Customer)
+			return nil
+		},
+	}
+
+	http.Handle("/chargebee/webhooks", handler.HTTPHandler())
+	log.Fatal(http.ListenAndServe(":8080", nil))
+}
+```
+
+Low-level: parse just the event type and unmarshal yourself:
+
+```go
+package main
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+
+	"github.com/chargebee/chargebee-go/v3/enum"
+	"github.com/chargebee/chargebee-go/v3/webhook"
+)
+
+func cbWebhook(w http.ResponseWriter, r *http.Request) {
+	defer r.Body.Close()
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	evtType, err := webhook.ParseEventType(body) // validates api_version too
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	switch evtType {
+	case enum.EventTypeSubscriptionCreated:
+		var e webhook.SubscriptionCreatedEvent
+		if err := json.Unmarshal(body, &e); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		// handle e
+	default:
+		// ignore or log
+	}
+	w.WriteHeader(http.StatusOK)
+}
+```
+
+#### Unhandled events
+
+By default, if an incoming webhook’s event type is unknown or you have not registered a corresponding handler on `WebhookHandler`, the SDK treats it as an error. When using `HTTPHandler()`, this results in a 500 response unless you provide a custom `OnError` handler.
+
+If you prefer to acknowledge unknown/unregistered events (return 200) and just log them, set `OnUnhandledEvent` to a function that returns `nil`:
+
+```go
+import (
+	"log"
+	"github.com/chargebee/chargebee-go/v3/enum"
+	"github.com/chargebee/chargebee-go/v3/webhook"
+)
+
+handler := &webhook.WebhookHandler{
+	OnUnhandledEvent: func(t enum.EventType, body []byte) error {
+		log.Printf("Ignoring unhandled event: %s", t)
+		return nil // swallow as OK
+	},
+}
+```
 
 ## Use the test suite
 ***

go.sum

@@ -1,17 +1,12 @@
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
-github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
-github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
-github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=