Developing locally with ngrok

This section illustrates how you can use ngrok to listen for transaction webhooks and serve your applications user-interface application during local development/testing.

ngrok is a useful tool for local web application development. It allows you to generate public URL's which tunnel traffic to the specified ports on your localhost.

Install ngrok

You can download and install ngrok from this location. Follow the instructions to unzip the executable in a folder. Next, sign up for an account on the ngrok website, and connect your instance of the ngrok client to your online account by copying your ngrok auth token from your account and running this command in your shell:

$ ngrok authtoken <YOUR_AUTHTOKEN>

Generate individual tunnels for serving user-interface and webhook requests

Create a new YAML file with the following content - specifying unique ngrok tunnels for your integrations user-interface and back-end application modules. This way - if you are running your user-interface on localhost:8080 and your back-end webhook listener on localhost:3000 - you can ask ngrok to create individual public URL's that tunnel traffic to each of these ports.

    proto: http
    addr: 8080
    proto: http
    addr: 3000

Save the above content in a file titled ngrok.yml in the appropriate location for the operating system:


Then, execute the following command in the ngrok shell:

$ ngrok start --all

This sets up two tunnels between and localhost:3000 and localhost:8080 on the computer. After the command is executed, this output appears on screen:

ngrok by @inconshreveable                                       (Ctrl+C to quit)
Session Status                online                                            
Account                       EPC (Plan: Free)                      
Version                       2.3.35                                            
Region                        United States (us)                                
Web Interface                                    
Forwarding           -> http://localhost:8080 
Forwarding           -> http://localhost:8080
Forwarding           -> http://localhost:3000 
Forwarding           -> http://localhost:3000
Connections                   ttl     opn     rt1     rt5     p50     p90       
                              0       0       0.00    0.00    0.00    0.00

Note that the public addresses of the tunnels created on are and

Register interfaceUrl and webhook URLs in product configuration

These two URLs can now be registered in the product configuration as the webhook URL and interfaceUrl respectively.

    "interfaceUrl": "",
    "webhooks": [
        "resource": "urn:elli:epc:transaction",
        "events": [
        "signingkey": "{{WEBHOOK_SHARED_SECRET}}",
        "url": ""

Did this page help you?