Webhooks- Creating an Endpoint

Introduction:

Webhooks are a powerful part of our Workflows engine. To learn more about Workflows, visit this article. 

Topics covered in this article:

Why Create an Endpoint?

Before you get started

How to create an Endpoint for Webhooks

Full Example

Have Questions?

Why Create an Endpoint?

An endpoint can be created to control the authentication and context of a webhook receiver. If additional information is needed from an available API, or custom code is required to process the payload of an incoming webhook, a consumer endpoint can be set up for processing as follows.

Before you get started

In addition to the code below, you'll also need to create a .env file with a WEBHOOK_SECRET key and a value.

WEBHOOK_SECRET=my-super-secret-code

How to create an Endpoint for Webhooks

Here are the steps to create an endpoint in Javascript (as an example):

• Set up a web server. We’ll be using node’s express library

const express = require('express'); // express web server
const bodyParser = require('body-parser'); // express application/json parser
const dotenv = require('dotenv');  // Provide access environment variables

dotenv.config();
const app = express();
app.use(bodyParser.json());

const port = process.env.PORT || 3000;

app.listen(port, () => {
  console.log(`Webhook consumer listening at http://localhost:${port}`);
});

• Authenticate the X-MM-Signature, an HMAC generated against the Webhook Secret created when configuring the webhook. We’ll be using node’s crypto library, and have express use this function to check every request.

const crypto = require('crypto');

function validateMMSignature(req, res, next) {
    const { body } = req;
    const mmSignature = req.headers['x-mm-signature'];
    const mmTimestamp = req.headers['x-mm-timestamp'];
    const url = req.headers['x-mm-request-uri'];
    
    // Create Verification String
    const prehashedSignature = 
        `${process.env.WEBHOOK_SECRET}
        ${mmTimestamp}
        POST
        ${url}
        ${JSON.stringify(body)}`;

    // Create HMAC using Webhook Secret
    const hmac = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET);
    const generatedSignature = hmac.update(prehashedSignature).digest('hex');
    
    if (generatedSignature !== mmSignature) {
        return res.status(403).send('Signatures do not match');
    }
    next();
}
app.use(validateMMSignature);

• Create your custom endpoints!

app.post('/', (req, res) => {
    res.status(200).send('Post Received');
});

app.post('/doSomeStuff', (req, res) => {
    const data = req.body.workflow;
    sendMessage(data.message);
    res.status(200).send('Message Sent');
});

Full Example

const express = require('express'); // express web server
const bodyParser = require('body-parser'); // express application/json parser
const dotenv = require('dotenv');  // Provide access environment variables
const crypto = require('crypto');

dotenv.config();
const app = express();
app.use(bodyParser.json());

function validateMMSignature(req, res, next) {
    const { body } = req;
    const mmSignature = req.headers['x-mm-signature'];
    const mmTimestamp = req.headers['x-mm-timestamp'];
    const url = req.headers['x-mm-request-uri'];
    
    // Create Verification String
    const prehashedSignature = 
        `${process.env.WEBHOOK_SECRET}
        ${mmTimestamp}
        POST
        ${url}
        ${JSON.stringify(body)}`;

    // Create HMAC using Webhook Secret
    const hmac = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET);
    const generatedSignature = hmac.update(prehashedSignature).digest('hex');
    
    if (generatedSignature !== mmSignature) {
        return res.status(403).send('Signatures do not match');
    }
    next();
}
app.use(validateMMSignature);

app.post('/', (req, res) => {
    res.status(200).send('Post Received');
});

const port = process.env.PORT || 3000;

app.listen(port, () => {
  console.log(`Webhook consumer listening at http://localhost:${port}`);
});

Have Questions?

Reach out to our Support Team at Support@machinemetrics.com.