Webhook Relay
DocumentationFundamentals

Read, write request data

How to access and modify request data in Webhook Relay Functions

In this page we will demonstrate basic operations that you can achieve in functions.

Accessing request data (incoming webhook/API request)

Functions use the r object that provides access to request data (headers, query, method and body) and can then update any HTTP request details.

Available data to access:

LuaJavaScriptTypeDescription
r.RequestBodyr.bodyStringRequest body.
r.RequestMethodr.methodStringRequest method (PUT, POST, DELETE, etc.).
r.RequestPathr.pathStringRequest path.
r.RequestRawQueryr.rawQueryStringRequest query, for example if the request was made with /api?category=electronics, then the query will be category=electronics.
r.RequestHeaderr.headersTable/ObjectA key-value map of headers.
r.RequestQueryr.queryTable/ObjectA key-value map of query params.

Read request body

An example of accessing request body and decoding it:

// request body is in r.body, use it as any other string:
const body = JSON.parse(r.body)

-- import json package
local json = require("json")

-- request body is in r.RequestBody, use it as any other string:
local body, err = json.decode(r.RequestBody)
if err then error(err) end

Reading request headers

To access specific header, use:

const myHeader = r.headers["Your-Header-Name"]

local my_header = r.RequestHeader["Your-Header-Name"]

Reading request URL query

To read request URL query (for example /v1/api?hub.mode=subscribe&hub.challenge=1903260781&hub.verify_token=my-token") you have two options:

  1. r.RequestQuery["hub.challenge"] / r.query["hub.challenge"] which will return 1903260781 for this example.
  2. r.RequestRawQuery / r.rawQuery which will return full raw query hub.mode=subscribe&hub.challenge=1903260781&hub.verify_token=my-token"

Modify request data

Available methods to update request:

LuaJavaScriptParameter TypeDescription
r:SetRequestBody("string")r.setBody("string")StringUpdate request body
r:SetRequestMethod("string")r.setMethod("string")StringUpdate request method
r:SetRequestRawQuery("foo=bar")r.setRawQuery("foo=bar")StringUpdate request raw query
r:SetRequestPath("/extra/path")r.setPath("/extra/path")StringSet additional extra path
r:SetRequestHeader("key", "value")r.setHeader("key", "value")String, StringSet new header key/value pair

An example how to update request object:

// set body
r.setBody("new body")
// set method
r.setMethod("POST")
// set raw query
r.setRawQuery("foo=bar")
// set extra path
r.setPath("/extra/path")
// set header
r.setHeader("Content-Type", "application/json")

-- set body
r:SetRequestBody("new body")
-- set method
r:SetRequestMethod("string")
-- set raw query
r:SetRequestRawQuery("foo=bar")
-- set extra path
r:SetRequestPath("/extra/path")
-- set header
r:SetRequestHeader("Content-Type", "application/json")

Modify response

Note: customized responses only applicable if function is attached to the Input and not bucket's Output.

Available methods to set customized response:

LuaJavaScriptParameter TypeDescription
r:SetResponseBody("string")r.setResponseBody("string")StringSet response body
r:SetResponseStatusCode(201)r.setResponseStatus(201)IntegerSet response status code
r:SetResponseHeader("key", "value")r.setResponseHeader("key", "value")String, StringSet response header key/value pair

Getting configuration values

Configuration values in functions allow sharing the code without sharing sensitive information or just configuration values that might change between accounts, teams, etc.

To add a new configuration value:

  1. Create a function
  2. Go to function details
  3. Click on a tab "CONFIG VARIABLES"
  4. Specify config variable key and value.

Once you have specified these details, you can start using them in your functions:

// configuration is accessible from a global "cfg" variable
const projectId = cfg.get("PROJECT_ID")
// do something with the value

-- configuration is accessible from a global "cfg" variable
local project_id = cfg:GetValue("PROJECT_ID")
-- do something with the value

Filtering requests

To filter requests based on body, headers or some external conditions, you can use the stop forwarding method. This will set webhook status to rejected and this webhook will not be forwarded:

// in this example we will check the payload to make the decision

// incoming request body example:
// {
//   "action": "important",
//   "user": "joe"
// }

const requestBody = JSON.parse(r.body)

// simple comparison of the payload
if (requestBody.action === "not_important") {
    // request is not important, don't forward it
    r.stopForwarding()
    return
}
// Otherwise, continue forwarding or add any additional logic here

-- in this example we will check the payload to make the decision
local json = require("json")

-- incoming request body example:
-- {
--   "action": "important",
--   "user": "joe"
-- }

local requestBody, err = json.decode(r.RequestBody)
if err then error(err) end

-- simple comparison of the payload
if requestBody["action"] == "not_important" then
    -- request is not important, don't forward it
    r:StopForwarding()
    return
end
-- Otherwise, continue forwarding or add any additional logic here
Did this page help you?