What are Functions?

Webhook Relay Functions provide an easy way to extract values from webhooks and transform HTTP requests before passing them to their final destination. Function can be reused by any number of Inputs and/or Outputs. Since user doesn’t have to run a server, this type of function service is also known as FaaS (Function as a Service) or Serverless.

Functions on Inputs transform webhooks when they enter the system and also allows you to customise both response that Webhook Relay will return and webhook request that will be passed along to all outputs.

Functions on Outputs allow you to customise webhooks for each destination. This way you can have a custom webhook arriving at each destination (Slack, Mattermost or some CRM system like HubSpot or Zoho).

Currently, you can write functions in Lua language which is perfect for most of the tasks.

Functions can be managed using relay CLI or through the web dashboard. You can create, edit and delete functions:

Creating a function

To create a new function, simply use relay function create command:

relay function create my-function.lua

You can also specify name, source and driver using optional flags:

• --driver lua or wasm (defaults to the extension.)

• --name name of the function (defaults to the name of the file)

• --source points to the location of the function file (usually .lua (version 5.1) or .wasm)

Function example (Lua)

In this example we will use a Lua 5.1 function that takes webhook JSON as an input and converts it to a Slack message JSON to display an alert for us in chat.

Mailgun JSON (shortened version, usually it’s a bit bigger):

{
    "signature": {
        "timestamp": "xx",
        "token": "xx",
        "signature": "xxx"
    },
    "event-data": {
        "severity": "permanent", 
        "log-level": "error",               
        "recipient": "[email protected]",
        "delivery-status": {
            "tls": true,
            "mx-host": "srv2.yyy.ccc",
            "attempt-no": 1,
            "description": "",
            "session-seconds": 2.601992130279541,
            "code": 550,
            "message": "High probability of spam",
            "certificate-verified": true
        }
    }
}

Below is a Lua function that converts Mailgun webhook into a Slack webhook:

-- mailgun_to_slack.lua
local json = require("json")
​
local body, err = json.decode(r.RequestBody)
if err then error(err) end
​
local message = "Mailgun mail delivery error! Severity: " .. body["event-data"]["severity"]  .. "  | Reason: " .. body["event-data"]["reason"] .. " | Resp: " .. body["event-data"]["delivery-status"]["message"]  .. " | Recipient: " .. body["event-data"]["recipient"]
​
-- Preparing Slack payload
local slack = {
    response_type= "in_channel", 
    text= message}
​
local result, err = json.encode(slack)
if err then error(err) end
​
-- Set request header to application/json for Slack API
r:SetRequestHeader("Content-Type", "application/json")
-- Set modified request body
r:SetRequestBody(result)

This function transforms it into a JSON that can be accepted by Slack incoming webhook API:

{
    "response_type": "in_channel",
    "text": "Mailgun mail delivery error! Severity: permanent  | Reason: generic | Resp: High probability of spam | Recipient: [email protected]"
}

To add this function to your account so we can use it later, type:

relay function create mailgun_to_slack.lua

Using functions

The easiest way to start using Functions is with the forward command:

relay forward --bucket mailgun-to-slack --function mailgun_to_slack --type public https://hooks.slack.com/services/xxx

This command will create a new bucket, input and output. Function will be attached to the output that’s forwarding to https://hooks.slack.com/services/xxx endpoint.

Alternatively, you can attach Functions to existing Inputs:

relay input update INPUT_ID -b BUCKET_NAME --function mailgun_to_slack

or Outputs

relay output update OUTPUT_ID -b BUCKET_NAME --function mailgun_to_slack

To stop using some particular function in your Input or Output, just update Function to “”:

relay input update INPUT_ID -b BUCKET_NAME --function ""

Viewing functions

You can view your uploaded functions via relay function ls command:

relay function ls
ID                                     NAME                 DRIVER              SIZE                AGE                 UPDATED AGO
a298cf54-480b-4c50-b275-a4336f75f26f   mailgun_to_slack     lua                 703 B               4 days              2 days
a1a29b1c-7415-4983-94d5-0472113efeb1   set_response_body    wasm                464 kB              8 days              8 days
db5e5b91-cdb2-4712-8413-c4f335218e3f   transform_to_slack   wasm                501 kB              10 days             10 days

Updating functions

To update a function, you have to specify the name and source location:

relay function update mailgun_to_slack --source mailgun_to_slack.lua

Deleting functions

To delete a function, first ensure that any Input or Output doesn’t use the function anymore. Once it’s done:

relay function rm mailgun_to_slack