Set up your local environment

Introduction

Using the Callback method requires that you have 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.

Pre-Requisites

You'll need a local development environment setup with;

* Node.js 13+

* NPM or Yarn

Set up Express

Express is a web framework for Node.js, install using NPM or Yarn

yarn add express

Express makes use of its own modules (termed middleware) to provide capabilities, body-parser is one we'll use;

shell
Copy to clipboard.
1yarn add express body-parser

Either clone the MATTR Sample apps from Github or create a folder and add in a file called callback-express.js with this content:

javascript
Copy to clipboard.
1'use strict'
2
3
4
5
6const express = require('express')
7
8const bodyParser = require('body-parser')
9
10
11
12
13const app = express()
14
15
16
17
18// Use body-parser middleware
19
20app.use(bodyParser.json())
21
22
23
24
25// Receive a POST request to /callback & print it out to the terminal
26
27app.post('/callback', function (req, res) {
28
29  const body = req.body
30
31  console.log(body)
32
33  res.sendStatus(200)
34
35})
36
37
38
39
40// listen on port 2000
41
42app.listen(2000, function (err) {
43
44  if (err) {
45
46    throw err
47
48  }
49
50
51
52
53  console.log('Server started on port 2000')
54
55})

In a terminal window start the app 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

Test it out by making a POST call

In a new terminal window use Curl to make a call and check that it is being returned.

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

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, however the MATTR Platform needs a publicly resolvable address to send the credential data to. A port forwarding service like Ngrok helps us out here.

> Note: 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.

In a 3rd terminal window, install and run Ngrok on the port defined in callback-express.js

shell
Copy to clipboard.
1yarn add global 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 8 hours. You will need to use the http version of the Forwarding URL.

Test out your public endpoint

Make another call using Curl but this time swap out localhost for your valid Ngrok domain and for clarity update your payload.

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

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