Development tunnels

When developing locally, your webhook handler might be available only at an address such as http://localhost:8080.

ePay cannot send webhooks to localhost that address refers to the machine making the request, not your computer. A development tunnel creates a public HTTPS URL and securely forwards its requests to your local application.

Choose a tunnel

ngrok

ngrok is the easiest option for receiving a webhook on your local machine. It runs a small command-line agent and gives you a public HTTPS URL.

1. Create a free ngrok account and install the ngrok agent.
2. Copy your authtoken from the ngrok dashboard and register it with the agent:

ngrok config add-authtoken <YOUR_AUTHTOKEN>

3. Start your application locally. In this example, the webhook route is served at http://localhost:8080/webhooks/epay.
4. In a second terminal, expose the application's port:

ngrok http 8080

ngrok prints a public forwarding URL, similar to this:

https://example-1234.ngrok-free.app

Use that URL plus your webhook path as the notificationUrl when you create a test payment:

{  "notificationUrl": "https://example-1234.ngrok-free.app/webhooks/epay"}

Keep ngrok running until ePay has delivered the webhook. The generated hostname can change when you restart the tunnel, so update the notification URL for each new test session.

For installation details and options, see the ngrok agent documentation.

Cloudflare Tunnel

Use a named Cloudflare Tunnel when you want a stable development URL, for example https://webhooks-dev.example.com. Your domain must be added to Cloudflare and use Cloudflare DNS.

1. Install cloudflared.
2. In the Cloudflare dashboard, go to Networking → Tunnels and create a tunnel.
3. Select your operating system, then run the command Cloudflare provides to connect your local machine. It has this form:

cloudflared tunnel run --token <TUNNEL_TOKEN>

4. Open the tunnel's Routes tab and add a Published application route:

5. Use the stable hostname and webhook path in your test payment:

{  "notificationUrl": "https://webhooks-dev.example.com/webhooks/epay"}

Keep cloudflared running while testing. The tunnel dashboard should report the tunnel as healthy before you create the payment.

For the complete setup flow, see Cloudflare's guide to create a remotely-managed tunnel.

Test the webhook handler

Before testing a payment, verify that your local route accepts a request:

curl --include --request POST http://localhost:8080/webhooks/epay \  --header 'Content-Type: application/json' \  --data '{}'

Then create a test payment with the tunnel URL as its notification URL. Treat the webhook exactly as you would in production: verify the payment result, make processing idempotent, and return a successful response after handling it. See Handle payment results for the webhook requirements.