Skip to main content
The webhooks command starts a local server and creates a public tunnel so ZendFi can deliver webhook events to your machine during development.

​
zendfi webhooks

zendfi webhooks [options]
Aliases: zendfi listen

​
Options

FlagDescriptionDefault
--port <port>Local port to listen on3000
--forward-to <url>Forward received webhooks to another local URL—

​
How It Works

1

Start local server

The CLI starts an Express server on the specified port (default 3000) with two endpoints:
EndpointMethodPurpose
/webhooksPOSTReceives webhook events from ZendFi
/healthGETHealth check returning { status: "ok", webhooksReceived: N }
2

Detect tunnel service

The CLI checks for ngrok and cloudflared on your system. If both are available, it prompts you to choose. If neither is installed, it shows installation links:
3

Create tunnel

Launches the selected tunnel service pointing to your local port. The CLI waits up to 30 seconds for the tunnel URL to become available.
4

Display configuration

Shows the public webhook URL and setup instructions:
✓ Local server started on port 3000
✓ Tunnel active: https://abc123.ngrok.io

Configuration:
  Webhook URL: https://abc123.ngrok.io/webhooks
  Health:      https://abc123.ngrok.io/health

Setup Instructions:
  1. Copy the webhook URL above
  2. Go to ZendFi Dashboard → Settings → Webhooks
  3. Add the webhook URL
  4. Create a test payment to trigger webhooks

Listening for webhooks... (Press Ctrl+C to stop)
5

Log incoming events

Each webhook event is logged with a timestamp, event counter, event type, payment ID, status, and amount:
[2:30:15 PM] Webhook #1 received
  Event:   payment.confirmed
  Payment: pay_test_7f3k9x2m
  Status:  ✓ CONFIRMED
  Amount:  $50 USD

[2:31:02 PM] Webhook #2 received
  Event:   settlement.completed
  Payment: pay_test_7f3k9x2m
  Status:  ✓ CONFIRMED
  Amount:  $50 USD

​
Forwarding

Use --forward-to to relay webhook payloads to your application’s actual webhook endpoint. This lets you test your real webhook handler while still seeing events in the CLI: 
zendfi webhooks --port 4000 --forward-to http://localhost:3000/api/webhooks/zendfi
The CLI receives the webhook on port 4000, logs it, and then forwards the full payload to your app at localhost:3000/api/webhooks/zendfi.

​
Tunnel Services

​
ngrok

The most popular option. The CLI reads the tunnel URL from ngrok’s stdout output. Free tier supports one tunnel at a time. 
# Install ngrok
brew install ngrok  # macOS
# or download from https://ngrok.com/download

​
Cloudflare Tunnel (cloudflared)

Free, no-signup alternative. Creates a *.trycloudflare.com URL automatically. 
# Install cloudflared
brew install cloudflare/cloudflare/cloudflared  # macOS
# or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

​
Shutdown

Press Ctrl+C to gracefully shut down. The CLI closes the local server, kills the tunnel process, and shows the total number of webhooks received during the session. 
Shutting down...
✓ Received 5 webhooks total

​
Testing Workflow

A typical local webhook testing session: 
# Terminal 1: Start your app
npm run dev

# Terminal 2: Start the webhook listener
zendfi webhooks --forward-to http://localhost:3000/api/webhooks/zendfi

# Terminal 3: Create a test payment to trigger events
zendfi payment create --amount 25 --watch
This creates a payment, which triggers payment.created and payment.confirmed webhooks. The CLI logs them, forwards them to your app, and your webhook handler processes them as it would in production.