Developing locally

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.

tunnels:
  user-interface:
    proto: http
    addr: 8080
  back-end:
    proto: http
    addr: 3000

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

/Users/{{user_id}}/.ngrok2/ngrok.yml

/Users/{{user_id}}/.ngrok2/ngrok.yml

C:\Users\{{user_id}}\.ngrok2\ngrok.yml

Then, execute the following command in the ngrok shell:

$ ngrok start --all

This sets up two tunnels between ngrok.io 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                 http://127.0.0.1:4040                             
Forwarding                    http://3d5e2d38.ngrok.io -> http://localhost:8080 
Forwarding                    https://3d5e2d38.ngrok.io -> http://localhost:8080
Forwarding                    http://db0a1b1c.ngrok.io -> http://localhost:3000 
Forwarding                    https://db0a1b1c.ngrok.io -> 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 ngrok.io are https://3d5e2d38.ngrok.io and https://db0a1b1c.ngrok.io.

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": "https://3d5e2d38.ngrok.io",
    "webhooks": [
      {
        "resource": "urn:elli:epc:transaction",
        "events": [
          "created",
          "updated"
        ],
        "signingkey": "{{WEBHOOK_SHARED_SECRET}}",
        "url": "https://db0a1b1c.ngrok.io"
      }
    ]
}