Guides
Webhook Setup
Set up local webhook testing with ngrok and verify webhook events from payment providers.
Payment providers like Tap send charge results asynchronously via webhooks. During local development, you need a public URL that tunnels to your local server. This guide walks through the complete setup with ngrok.
Prerequisites
- ngrok installed and authenticated
- The hosted checkout running locally on port 3100
Set Up the Tunnel
Start the hosted checkout
cd apps/hosted-checkout
pnpm dev
Start ngrok
In a separate terminal, start an ngrok tunnel:
ngrok http 3100
ngrok displays a public URL like https://abc123.ngrok-free.app.
Update APP_URL
Set the APP_URL environment variable to the ngrok URL:
apps/hosted-checkout/.env
APP_URL="https://abc123.ngrok-free.app"
Restart the dev server for the change to take effect.
How Webhooks Flow
Webhook Flow
Development Tunnel
🌐Customer Browser
🖥Your Server
🔗Dev Tunnel
💳Payment Gateway
Submit Payment
Create charge (webhook URL = tunnel)
3D Secure Verification
Complete Verification
POST webhook (payload + signature)
Forward to localhost
Verify Signature → Update Order
Customer Browser
Your Server
Dev Tunnel
Payment Gateway
Documentation Asset // COMMERCE_JS_SEQ_02