Webhook forwarding

Use chargebee listen to forward webhook events from your Chargebee test site to a local server, without setting up a public URL or a separate tunneling tool.

Before you start

Configure a test site. Forwarding is unavailable on live sites.
Set your profile’s site region to us, eu, or au, matching where your site is hosted.

Start forwarding

Run the listener with your webhook handler’s URL:

chargebee listen --forward-to http://localhost:3000/webhooks

Trigger an event on your test site:

chargebee customer create -d email=ada@example.com

The listener displays the HTTP status returned by your handler.

What your handler receives

Each event arrives as an HTTP POST request with:

The webhook payload as a JSON body.
Content-Type: application/json.
An X-Chargebee-Event-Type header containing the event type.

If forwarding fails, the CLI reports the error and keeps listening.

Set the forwarding URL

--forward-to (or -f) accepts an HTTP or HTTPS URL. For local servers, you can also use a shorthand:

Shorthand	Destination
`3000`	`http://localhost:3000`
`3000/webhooks`	`http://localhost:3000/webhooks`
`localhost:3000/webhooks`	`http://localhost:3000/webhooks`

Remote destinations are supported. The CLI warns when forwarding outside your machine because webhook payloads can contain customer data.

Use another profile

Select a saved test-site profile with --use-profile. This does not change your active profile:

chargebee --use-profile sandbox listen --forward-to 3000/webhooks

Stream CLI webhook forwarding as JSON

Add --json for scripts or AI agent workflows:

chargebee listen --forward-to 3000/webhooks --json

The CLI writes one JSON record per line. Each record includes type and timestamp. These records describe forwarding activity and exclude webhook payloads.

Type	Meaning	Additional fields
`connecting`	Opening the connection	`message`
`ready`	Ready to forward events	`forward_to`
`forward_result`	Event delivered; includes your server’s HTTP status	`event_type`, `http_status`
`forward_failed`	Event could not be delivered	`event_type`, `message`
`warning`	Nonfatal warning, written to `stderr`	`message`
`stopped`	Forwarding ended	None

Troubleshooting

Problem	Fix
Listener refuses to start on a live site	Configure a test site or select a test-site profile with `--use-profile`.
Event cannot reach your server	Start your server and check the port and path in `--forward-to`.
Tunneling is unavailable for the configured region	Run `chargebee auth add --region <region>` with your site’s region: `us`, `eu`, or `au`.
Forwarding URL is invalid	Use an `http://` or `https://` URL, or a local shorthand such as `3000/webhooks`.

Configuration: site regions and saved profiles.
Webhook events: event types and payloads.