Combining your Gumloop flows with webhook triggers allows you to build APIs visually with no code!

​
Webhooks

All Gumloop flows can be triggered via your own external app using webhooks.

To see the code necessary to trigger your flow, navigate to your flow and click the ‘Webhooks’ button on the top left side of the pipeline builder.

​
Authorization

When making requests to trigger your Gumloop flows, you can authenticate using one of two methods:

​
API Key in URL

The default method is to include your API key as a query parameter in the URL. This method is simpler and works well for most integrations:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx&api_key=xxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{}'

​
Authorization Header

Alternatively, you can use the Authorization header with a Bearer token. This method is preferred when you want to keep credentials out of URLs:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{}'

You can switch between these methods in the webhook modal by checking or unchecking the “Use Authorization Header” option.

All examples below use the Authorization header method, but you can substitute the API key method in any of them.

​
Inputs

Most useful flows require some input from the user. There are two main approaches to handle inputs in your Gumloop flows:

This is the recommended approach for handling inputs. Use a Webhook Input node to capture the entire request body as a string, then parse it using a JSON Reader node. This method provides maximum flexibility and makes it easy to handle complex, nested data structures.

With this approach, you can send any JSON structure directly in your request body:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{
    "recipient": "recipient@gmail.com",
    "subject": "Example of an Email Subject Line",
    "body": "Example of the Text of an Email Body",
  }'

The Webhook Inputs node will capture this entire JSON payload as a string, which you can then parse using a JSON Reader node to extract individual fields or work with the entire data structure.

​
Alternative Method: Named Input Nodes

While the webhook inputs node with JSON parsing is recommended, there is an alternative method for receiving data that uses named Input nodes. All the following options require you to set up Input nodes in your flow where the ‘Input name’ values represent the name of that input field. These input names are used to map the information you send via the webhook to the appropriate nodes.

Once you have set up your named Input nodes, you can choose from any of the following options to send data to your flow:

​
Option 1: Direct Field Mapping

Just like with the Webhook Input node, you can pass inputs by name directly in the body of the request. This approach is concise and straightforward:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{
    "recipient": "recipient@gmail.com",
    "subject": "Example of an Email Subject Line",
    "body": "Example of the Text of an Email Body"
  }'

​
Option 2: Using the pipeline_inputs Array

Alternatively, you can send inputs using the pipeline_inputs field in the request body. The pipeline_inputs field should contain an array of objects, where each object has an input_name that matches your Input node’s name and a value containing the data you want to pass to that Input node.

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -d '{
    "pipeline_inputs": [
      {"input_name": "recipient", "value": "recipient@gmail.com"},
      {"input_name": "subject", "value": "Example of an Email Subject Line"},
      {"input_name": "body", "value": "Example of the Text of an Email Body"}
    ]
  }'

​
Option 3: GET Request (For Services Without POST Support)

Flows can also be triggered using a GET request when your external service doesn’t support POST requests. In this case, all body fields are passed in the URL query parameters.

Inputs are passed as an array of objects with the pipeline_inputs query parameter as a URL-encoded string.

curl --get https://api.gumloop.com/api/v1/start_pipeline? \
  -d user_id=xxxxxxxxxxxxxx \
  -d saved_item_id=xxxxxxxxxxxxxx \
  -d api_key=xxxxxxxxxxxxxx \
  -d pipeline_inputs=%5B%7B%22input_name%22%3A%20%22recipient%22%2C%20%22value%22%3A%20%22recipient%40gmail.com%22%7D%2C%20%7B%22input_name%22%3A%20%22subject%22%2C%20%22value%22%3A%20%22Example%20of%20an%20Email%20Subject%20Line%22%7D%2C%20%7B%22input_name%22%3A%20%22body%22%2C%20%22value%22%3A%20%22Example%20of%20the%20Text%20of%20an%20Email%20Body%22%7D%5D

The value of pipeline_inputs is a URL-encoded string equivalent to the following JSON body:

[
  { "input_name": "recipient", "value": "recipient@gmail.com" },
  { "input_name": "subject", "value": "Example of an Email Subject Line" },
  { "input_name": "body", "value": "Example of the Text of an Email Body" }
]

Important limitation: Because inputs are passed in the URL, they are subject to URL length limitations. Maximum URL length limits vary by browser, but are typically around 2000 characters. If your inputs are longer than this, you must use the POST request method.

When using any of the above methods to trigger a flow, any provided headers will also be passed along as inputs to the flow. If you have an Input node with the same name as a header, it will be provided the header value as input.

This method is not recommended for regular use, but can be useful in specific integration scenarios:

curl -X POST \
  https://api.gumloop.com/api/v1/start_pipeline?user_id=xxxxxxxxxxxxxx&saved_item_id=xxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -H "recipient: recipient@gmail.com" \
  -H "subject: Example of an Email Subject Line" \
  -H "body: Example of the Text of an Email Body" \
  -d '{}'

​
Outputs

When you run a Gumloop pipeline remotely, the POST request to https://api.gumloop.com/api/v1/start_pipeline will return a run_id and a URL that links to the flow run.

Here is an example of the response:

{
  "run_id": B7uiXDngvzFvUWxHRKQFAD,
  "saved_item_id": q3dasHQBidkNeXvAZo6Dby,
  "url": https://www.gumloop.com/pipeline?run_id=B7uiXDngvzFvUWxHRKQFAD&flow_id=q3dasHQBidkNeXvAZo6Dby
}

You can use run_id to poll a separate endpoint to get information about the ongoing run like the status, logs, and outputs when it is completed.

In order to poll, make a GET request to https://api.gumloop.com/api/v1/get_pl_run with run_id as a query parameter.

Here is an example of a GET request with cURL, Python, and JavaScript and their outputs:

Request with cURL

curl 'https://api.gumloop.com/api/v1/get_pl_run?run_id=B7uiXDngvzFvUWxHRKQFAD&user_id=your_user_id' \
  -H 'Authorization: Bearer xxxxxxxxxxxxx'

Request with Python

import requests

url = "https://api.gumloop.com/api/v1/get_pl_run?run_id=B7uiXDngvzFvUWxHRKQFAD&user_id=your_user_id"
headers = {
    "Authorization": "Bearer xxxxxxxxxxxx"
}

response = requests.get(url, headers=headers)
print(response.json())

Request with JavaScript

const url = 'https://api.gumloop.com/api/v1/get_pl_run?run_id=B7uiXDngvzFvUWxHRKQFAD&user_id=your_user_id';
const headers = {
  Authorization: 'Bearer xxxxxxxxxxxxxx',
};

fetch(url, {
  method: 'GET',
  headers: headers,
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Output

{
    "created_ts": "2023-11-19T18:06:31.102786+00:00",
    "finished_ts": null,
    "log": [
        "\u001b[34m__system__: __STARTING__:Read files from GitHub\u001b[0m"
    ],
    "outputs": {},
    "run_id": "B7uiXDngvzFvUWxHRKQFAD",
    "state": "RUNNING",
    "user_id": "your_user_id"
}

The key attributes here are log, state, and outputs.

log: Contains a running log of each node and the activities within it.

state: One of “STARTED”, “RUNNING”, “TERMINATED”, “FAILED” or “DONE”.

outputs: A JSON object with key-value pair where the key is the output name and the value is the output value. This will only be populated when your pipeline reaches a “DONE” state and you have named output nodes in your pipeline.