Making HTTP Requests

Functions can call 3rd party HTTP servers to get additional information for your webhook or just make an API call and end function execution.

Functions can make multiple HTTP request calls to any external server. Some of the uses cases:

  • Call 3rd party API to get additional authentication tokens before forwarding request.

  • Send data to the external service directly, without relying on the webhook.

  • Get additional data to the function so it can dynamically mutate the payload.

Using HTTP package

To make an HTTP request from Lua function, import ‘http’ package:

-- importing HTTP package
local http = require("http")

-- making HTTP call
response, err = http.request("GET", "https://example.com")
if err then error(err) end

-- parsing response body from the API
local api_response, err = json.decode(response.body)
if err then error(err) end

Specify request body

You can also make a POST, PUT, DELETE requests to a 3rd party APIs:

-- importing HTTP and JSON packages
local json = require("json")
local http = require("http")

local payload, err = json.encode({
    action = "create_record",
    user = "example",
})
if err then error(err) end

local resp, err = http.request("POST", "http://example.com/api", { body = payload})
if err then error(err) end

Reading response body

To read response body:

-- importing HTTP package
local http = require("http")

-- making HTTP call
response, err = http.request("GET", "https://example.com")
if err then error(err) end

-- received JSON string:
-- {
--   "firstname": "luke",
--   "lastname": "skywalker"  
-- }

-- parsing response body from the API
local api_response, err = json.decode(response.body)
if err then error(err) end

-- access values like 'api_response.firstname'

Query, headers, timeout

To specify query, timeout and headers:

-- importing HTTP package
local http = require("http")

-- specifying headers
local headers = {}
headers["Authorization"] = "Basic " .. "123456"

-- making HTTP call
response, err = http.request("GET", "https://example.com", {
    query="page=1",
    timeout="5s",
    headers={
        Accept="*/*"
    }
})
if err then error(err) end

-- parsing response body from the API
local api_response, err = json.decode(response.body)
if err then error(err) end

Batch requests

To send multiple requests asynchronously, create a table containing the requests and call the http.request_batch method:

local http = require("http")

-- Prepare a table with requests. Each row in this table contains a table 
-- that needs to have a request method and a URL. You can also add options
-- that add query arguments, authentication, headers, body, etc.
local requests = {
    {"GET", "https://first.example.com", {query="page=1"}},
    {"POST", "https://second.example.com", auth={user="user", pass="pass"}},
    {"PUT", "https://third.example.com", {form="username=john&password=wick"}},
    {"PATCH", "https://fourth.example.com", 
      {
        headers={
	  ["Content-Type"]="application/json"
        },
        body = '{"elon": "musk"}'
      }
    },
}

-- Dispatch the requests and wait for all the responses
responses, errors = http.request_batch(requests)
if errors then error(errors) end

-- If you need to do something with the responses or 
-- errors, you can view them:
local errorStrings = {}
for _, err in pairs(errors) do
    table.insert(errorStrings, tostring(err))
end
table.sort(errorStrings)

-- To access response:
if responses[2]["body"] == "not-expected" then
    -- Do something
end

Since all requests are launched asynchronously,

HTTP package API reference

http.delete(url [, options])

Attributes

Name

Type

Description

url

String

URL of the resource to load

options

Table

Additional options

Options

Name

Type

Description

query

String

URL encoded query params

cookies

Table

Additional cookies to send with the request

headers

Table

Additional headers to send with the request

Returns

http.response or (nil, error message)

http.get(url [, options])

Attributes

Name

Type

Description

url

String

URL of the resource to load

options

Table

Additional options

Options

Name

Type

Description

query

String

URL encoded query params

cookies

Table

Additional cookies to send with the request

headers

Table

Additional headers to send with the request

Returns

http.response or (nil, error message)

http.head(url [, options])

Attributes

Name

Type

Description

url

String

URL of the resource to load

options

Table

Additional options

Options

Name

Type

Description

query

String

URL encoded query params

cookies

Table

Additional cookies to send with the request

headers

Table

Additional headers to send with the request

Returns

http.response or (nil, error message)

http.patch(url [, options])

Attributes

Name

Type

Description

url

String

URL of the resource to load

options

Table

Additional options

Options

Name

Type

Description

query

String

URL encoded query params

cookies

Table

Additional cookies to send with the request

body

String

Request body.

form

String

Deprecated. URL encoded request body. This will also set the Content-Type header to application/x-www-form-urlencoded

headers

Table

Additional headers to send with the request

Returns

http.response or (nil, error message)

http.post(url [, options])

Attributes

Name

Type

Description

url

String

URL of the resource to load

options

Table

Additional options

Options

Name

Type

Description

query

String

URL encoded query params

cookies

Table

Additional cookies to send with the request

body

String

Request body.

form

String

Deprecated. URL encoded request body. This will also set the Content-Type header to application/x-www-form-urlencoded

headers

Table

Additional headers to send with the request

Returns

http.response or (nil, error message)

http.put(url [, options])

Attributes

Name

Type

Description

url

String

URL of the resource to load

options

Table

Additional options

Options

Name

Type

Description

query

String

URL encoded query params

cookies

Table

Additional cookies to send with the request

body

String

Request body.

form

String

Deprecated. URL encoded request body. This will also set the Content-Type header to application/x-www-form-urlencoded

headers

Table

Additional headers to send with the request

Returns

http.response or (nil, error message)

http.request(method, url [, options])

Attributes

Name

Type

Description

method

String

The HTTP request method

url

String

URL of the resource to load

options

Table

Additional options

Options

Name

Type

Description

query

String

URL encoded query params

cookies

Table

Additional cookies to send with the request

body

String

Request body.

form

String

Deprecated. URL encoded request body. This will also set the Content-Type header to application/x-www-form-urlencoded

headers

Table

Additional headers to send with the request

Returns

http.response or (nil, error message)

http.request_batch(requests)

Attributes

NameTypeDescription

requests

Table

A table of requests to send. Each request item is by itself a table containing http.request parameters for the request

Returns

[http.response] or ([http.response], [error message])

http.response

The http.response table contains information about a completed HTTP request.

Attributes

Name

Type

Description

body

String

The HTTP response body

body_size

Number

The size of the HTTP response body in bytes

headers

Table

The HTTP response headers

cookies

Table

The cookies sent by the server in the HTTP response

status_code

Number

The HTTP response status code

url

String

The final URL the request ended pointing to after redirects

Last updated