Webhook Liaison

A configurable filtering/transforming proxy for Webhooks / HTTP requests.

Webhook-liason converts request data to JSON, limits subsequent requests via filters and finally transforms the request JSON into the destination(s) format to be sent.

Features

• Filters & transformations are powered by super powerful JMESPath query language.
• Runs on AWS Lambda using Serverless Framework so its low maintenance and probably free(< 1 million requests a month).
• Single inbound Webhook can trigger multiple outbound Webhooks each with its own filters & transformations.
• Supports application/x-www-form-urlencoded & application/json content-types for inbound/outbound requests.
• Handles GET requests & query string parameters.
• HTTP authentication.

Examples

• Github -> Slack: Post to Slack when a pull request is labelled.
• Travis-CI -> IFTTT: Trigger IFTTT when tests fail / fixed on master.
• Papertrail -> Twillio(SMS): Send SMS via Twillio when errors are detected on Papertrail.

Installation

Run Locally

• npm install && npm start
• Configure

test: curl -X POST -d '{"json": "data"}' http://localhost:3000/hook/<config-name>

Deploy to AWS Lambda

• Install the Serverless Framework.
• Clone this repo.
• Configure
• Deploy sls dash deploy.
• Test / check cloud watch logs.

test: curl -X POST -d '{"json": "data"}' http://<aws-lambda-url>.com/webhookliaison/hook/<config-name>

Operations

Operations are all powered by the JMESPath query language and can be defined at both destination and root level. Operations configured at the destination level will be applied to the output of the root level operations.

See JMESPath tutorial to learn the syntax / test your queries.

Filters

Control when subsequent requests are sent. They are defined as a list of JMESPaths queries that will block the webhook from being triggered if they return a falsy value.

filters: [
  "successMessage",  // filter if missing successMessage
  "attribute  == `success`", // filter if attribute do not equal success.
  "length(errors[? severity == `critical`]) > `2`", // filter if less then 2 critical errors
]

Transformations

Modify the JSON data(all request data types are converted to JSON) via a map of key : JMESPaths. Existing attributes will be preserved and new attributes will be merged in.

transformations: [
  {
    worldCities: "countries[].states[].cities[].name | sort(@)", // sorted list of cities.
    listOfAttributes: "[ countries[0].name, countries[1].name ]", // list of selected attributes
    msg: "join(' ', ['Hello', user.firstName, user.lastName])", // concat attributes and text into string
    details: "{ name: users[0].name, email: people[0].email }", // create object from attributes
    errors: "actions.*.errors", // create list of errors (if any) from nested data
  }
]

Extractions

Modify the JSON data exactly the same way as transformations except they start with a blank state (only attributes/selectors you define will be included in request).

Configuration Options

Configuration file supports JSON5 which allows a cleaner syntax + comments. Example configuration can be found in here.

• jsonEmbededFormParameter: Extract URIEncoded JSON data from x-www-form-urlencoded field.
• filters: See filters for details.
• extractions: See extractions for details.
• transitions: See transitions for details.
• destinations: destination(s) define subsiquent wehbooks to be sent.
  • url: url to make request against.
  • contentType: Content type for request data (Will be converted to JSON).
  • auth: HTTP authentication parameters.
    • user: HTTP authentication user name.
    • pass: HTTP authentication password.

Non Webhook Enabled Services

All HTTP methods are supported + authentication. Form & JSON content types, GET method and query string parameters so if it supports HTTP requests you can probably interact with it.

Common Issues

Unable to import module '_serverless_handler' : Happens if you sls dash deploy in directory other than app root.