Tutorial Step 1 - A Basic Webhook

In the first step of the tutorial, we're going to create an event handler (webhook) which is compatible with Adobe I/O Events. This webhook doesn't actually do much; it just logs the body of the request. But it provides a skeleton on which you'll build in later steps.

Dependencies

To write the webhook, this tutorial uses Express, a minimal web framework for Node.js. To automate the parsing of JSON requests, the body-parser package is used. Finally, a package named dotenv is used to parse and load the .env file created in the Overview. To install these three packages, run

npm install express body-parser dotenv
CopyCopied to your clipboard
npm install express body-parser dotenv

Writing the Webhook Script

Now you're ready to write the webhook script itself. Create a new file named index.js and open it in your IDE.

The webhook script itself has four main parts. The first part is including the dependencies, loading the .env file, and setting up the Express application:

const express = require("express");
const bodyParser = require("body-parser");

require("dotenv").config();

const app = express();

app.use(bodyParser.json());
CopyCopied to your clipboard
1const express = require("express");
2const bodyParser = require("body-parser");
3
4require("dotenv").config();
5
6const app = express();
7
8app.use(bodyParser.json());

The second and third parts are the Express routes. These are JavaScript functions that handle specific request patterns. An Adobe I/O webhook must handle two different types of requests.

1. It must handle GET requests with a challenge query string parameter by responding with the challenge parameter.
2. It must handle POST requests by responding with a 200 status code. This is how the actual events will be received.

For the purpose of this tutorial, the path /webhook is used. This can be any path, even just /, but the same path must be used for both the GET and POST routes.

The challenge handler looks like this:

app.get('/webhook', (req, res) => {
  if (req.query['challenge']) {
    res.set('Content-Type', 'text/plain')
    res.send(req.query['challenge'])
  } else {
    console.log('No challenge')
    res.status(400)
    res.end()
  }
})
CopyCopied to your clipboard
1app.get('/webhook', (req, res) => {
2  if (req.query['challenge']) {
3    res.set('Content-Type', 'text/plain')
4    res.send(req.query['challenge'])
5  } else {
6    console.log('No challenge')
7    res.status(400)
8    res.end()
9  }
10})

For the POST handler, at this point in the tutorial, it should just log the body and then write something trivial as a response.

app.post('/webhook', (req, res) => {
  console.log(req.body)
  res.set('Content-Type', 'text/plain')
  res.send('pong')
})
CopyCopied to your clipboard
1app.post('/webhook', (req, res) => {
2  console.log(req.body)
3  res.set('Content-Type', 'text/plain')
4  res.send('pong')
5})

The last part of the script is to start listening for requests. Here, the PORT variable specified in the .env file is used.

const listener = app.listen(process.env.PORT, () => {
  console.log(`Your app is listening on port ${listener.address().port}`);
});
CopyCopied to your clipboard
1const listener = app.listen(process.env.PORT, () => {
2  console.log(`Your app is listening on port ${listener.address().port}`);
3});

Running the Webhook Script

You have at least two options to run the webhook script. The first way is to simply run it locally with

node index.js
CopyCopied to your clipboard
node index.js

You should see a message that it is up and running:

Your app is listening on port 4000
CopyCopied to your clipboard
Your app is listening on port 4000

Creating a Tunnel with ngrok

In order to use the webhook with Adobe I/O, it must be accessible to the public internet. But, your development machine is probably not accessible. So you need to open a tunnel allowing public access to the webhook. One popular tool for doing this is ngrok. Follow the instructions on the ngrok website to install it. Once it is installed, you can open up a tunnel by running

ngrok http 4000
CopyCopied to your clipboard
ngrok http 4000

Once running ngrok will show you two forwarding addresses:

Forwarding                    http://e639e8fd.ngrok.io -> localhost:4000
Forwarding                    https://e639e8fd.ngrok.io -> localhost:4000
CopyCopied to your clipboard
1Forwarding                    http://e639e8fd.ngrok.io -> localhost:4000
2Forwarding                    https://e639e8fd.ngrok.io -> localhost:4000

Running the Webhook Script with Glitch

Alternatively, you can run the webhook script using Glitch. Glitch is an interactive web-based code editor for Node.js applications with built-in hosting. To save you the trouble of copy and pasting the files you've created already, you can just click the button below to create a new application on Glitch pre-populated with the content of the tutorial so far.

In the new Glitch project, you will need to populate the .env file and create the .data/private.key file as describe in the introduction.

Registering the Webhook with Adobe I/O

Now that you have your webhook running at a publicly accessible URL, you can register it with Adobe I/O. To do this, open the Adobe Developer Console and open the Project you created in Step 0. Click Add to Project and select Event. Select Cloud Manager and click Next.

Select the events you want to subscribe to. For the purpose of this tutorial, you will need at least the Pipeline Execution Started event. Click the Next button.

There are three options for receiving events: Journaling, Webhooks, and Runtime actions. For the purpose of this tutorial, select the Webhook option.

If you are using ngrok, the Webhook URL will be the Forwarding address appended with /webhook, e.g. https://e639e8fd.ngrok.io/webhook. If you are using Glitch, the URL will be the Glitch application name appended with .glitch.me/webhook, e.g. https://enchanted-bathroom.glitch.me/webhook

Next Step

With all that done, you're ready to proceed to the next step. Continue to Step 2.

Last updated 3/4/2022

Was this helpful?

Yes

No