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).

Prerequisites

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:

shell
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:

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

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

shell
Copy to clipboard.
1node callback-express.js

https://www.datocms-assets.com/38428/1621287048-callback-express-started.webp?auto=format

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

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

https://www.datocms-assets.com/38428/1621287106-callback-express-payload.webp?auto=format

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

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

https://www.datocms-assets.com/38428/1621287259-callback-ngrok.webp?auto=format

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:

shell
Copy to clipboard.
1curl --request POST \
2  --url http://71df02cc96e5.ngrok.io/callback \
3  --header 'Content-Type: application/json' \
4  --data '{
5  "ngrok": "routed"
6}'

Your Ngrok window shows the routing:

https://www.datocms-assets.com/38428/1621287165-callback-ngrok-req.webp?auto=format

Your Express window shows the parsed payload:

https://www.datocms-assets.com/38428/1621287133-callback-express-ngrok.webp?auto=format

What's next?

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