Setup your local environment

Verifying a credential using a callback URL requires an endpoint that can accept application/json content-type and is publicly available. For this tutorial we will setup a local environment using a simple Node.js framework (Express) and a hosted public request forwarder (Ngrok).


You'll need a local development environment setup with:

  • Node.js 13+

  • NPM or Yarn

Setup Express

1. Express is a web framework for Node.js. Install it using NPM or Yarn

yarn add express

2. Express makes use of its own modules (termedy middleware) to provide capabilities. We will use body-parser , so add it to your environment:

Copy to clipboard.
1yarn add express body-parser

3. Either clone the MATTR Sample apps repo or create a folder and add a file named callback-express.js with the following content:

Copy to clipboard.
1'use strict'
2const express = require('express')
3const bodyParser = require('body-parser')
4const app = express()
6// Use body-parser middleware
10// Receive a POST request to /callback & print it out to the terminal
11'/callback', function (req, res) {
13    const body = req.body
14    console.log(body)
15    res.sendStatus(200)
18// listen on port 2000
20app.listen(2000, function (err) {
21    if (err) {
22        throw err
23    }
24    console.log('Server started on port 2000')

4. Start the app in a terminal window to create a server listening for calls to /callback on the specified port.

Copy to clipboard.
1node callback-express.js

5. Open a new termianl window and test your step by making the following POST request and checking that it is being returned:

Copy to clipboard.
1curl --request POST \
2  --url http://localhost:2000/callback \
3  --header 'Content-Type: application/json' \
4  --data '{
5  "json": "payload"

Set up Ngrok

Having a server running locally is fine for calls you generate, but MATTR VII needs a publicly resolvable address to send the credential data to. A port forwarding service like Ngrok helps us out here.

Credential data is going to be sent to the external service, please ensure you understand the privacy policy of any 3rd party you decide to go with for the purpose of this tutorial.

1. Sign up for Ngrok (it's free) and follow the instructions to retrieve a token and apply it to your environment.
2. In a new terminal window, install and run Ngrok on the port defined in callback-express.js

Copy to clipboard.
1yarn global add ngrok
3ngrok http 2000

Every time you start an instance of Ngrok a new forwarding URL is generated that will last for eight hours. You will need to use the http version of the Forwarding URL.

2. Test your public endpoint by making another but this time swap out localhost with your valid Ngrok domain, and for clarity update your payload as well:

Copy to clipboard.
1curl --request POST \
2  --url \
3  --header 'Content-Type: application/json' \
4  --data '{
5  "ngrok": "routed"

Your Ngrok window shows the routing:

Your Express window shows the parsed payload:

What's next?

Now that your local environment is setup, you can continue to create a presentation request.