Webhooks & HTTP

Webhooks are a way of transferring information into and out of web apps through simple HTTP posts, usually containing data in some kind of structured format (JSON or form key/values).

If that makes no sense whatsoever, then don't worry too much, it's not that difficult once you get going. However, you might find it easier to learn the concept of webhooks by receiving webhooks first, rather than sending them (as sending involves a few more steps).

Receiving Webhooks

In Flow XO, you'll receive a webhook via a trigger. To set up a webhook, start a new flow, and click the + button to create a new trigger.

You'll then see your choices for the trigger, select Webhook. The next thing you'll see is a unique URL for this trigger, which will look something like this:

https://flowxo.com/hooks/qqkmwxwk

Most of the time, you'll want to move data between a cloud app that supports webhooks into a Flow XO flow. So now's the time to figure out how to set up your webhook in your application, and copy and paste this URL into the other app.

When you've done that, you'll need to fire off a test webhook. That means taking the action in the app that triggers the webhook (usually creating something new). We do this for 2 reasons:

  1. To make sure it works!
  2. So that we know what to expect, so we can let you drag/drop the info you'll get from your webhook into the rest of your flow.

Here's what you'll see whilst we wait for your test:

Once you've sent the test (it might take a minute or two to be received), you should see:

That's actually all there is to it! After you've named the trigger (something more memorable than just 'Webhook'), you'll have a flow that is triggered every time you take the action in your app.

IMPORTANT NOTE:
The fields you send to the webhook initially during the webhook configuration will be recorded and made available for later use in your flows. Only the fields present in the initial test will be read by Flow XO in the future, so it is important to make sure that the initial request during the webhook testing phase will use the actual payload you expect to receive from the service you are integrating with. 

To see what information the flow received from the trigger, you'll need to create another task and take a look at the outputs that are available to you.

Acceptable Formats

When receiving webhooks, Flow XO takes care of recognising the format and converting the structured data into outputs that can be used later in other tasks.

Currently, we recognise data sent in these formats:

  • JSON (objects only, although the object may contain arrays)
  • XML
  • Form data
  • URL query string - you can make HTTP GET requests and use a query string in your URL. Note that values in the query string are only recognised in GET requests.
  • No data - you don't have to send anything. You might want a webhook to start a flow without passing any information in.

Manually Firing a Webhook

If you hit a Flow XO webhook URL in your browser, you're making a perfectly valid HTTP GET request that will work as a trigger. In some situations you might find it useful to trigger a flow manually by hitting the URL in your browser, or even creating a shortcut to it on your desktop for quick access.

As explained above, you can also use a query string in your URL:

https://flowxo.com/hooks/qqkmwxwk?this_key=this_value

So every time you hit the webhook, your flow will have the output this_key set to whatever value you give in the URL.

Making HTTP Requests

You can make HTTP requests by selecting the Webhook & HTTP service, then choosing Make a HTTP Request. Flow XO can send requests in formats that a wide range of services expect, but there are some things to note:

  • You can send data as JSON (content type application/json) or form data (content type application/x-www-form-urlencoded). The content-type header is automatically added for you.
  • There's also an option to send a raw body, which along with a suitable manually added content-type header, allows you to send any other type of data, including XML or plain text.
  • Headers can be added to the request.
  • There's support for basic authentication, which converts the credentials you give into an Authorization header. Note that if you also explicitly provide an authorization header, this will override it.
  • You can use nested JSON in your requests, and also choose to send your JSON wrapped in an array. See the JSON Options section below to see how.

Data

You can either have the request  send all the data collected so far (by not adding any specific key/values), or tell the request what data to send by adding at least one key/value.

Click Add under the Data section to add a new key/value to your request:

You'll see that you can also drag output values from previous tasks (or the trigger) to use as data. The key/values will be translated and encoded into your chosen format:

JSON Form 
{
  "Name": "John",
  "Phone": "020 7946 0000"
}<br>
		
Name=John&Phone=020+7946+0000

JSON Options

To send nested JSON, you should make sure that Enable JSON nesting is ticked, and use double underscores (__) to notate your nesting.

For example, using the key address__line1 with JSON nesting enabled, sends the data:

{
  "address": {
    "line1": "The Value"
  }
}

It's also possible to sub-nest your data ( address__line1__house_number).

Some services expect a JSON array, even though we're only sending a single object. To do this, tick the option to Wrap the JSON object in an array. The same request as in the example above would then send:

[{
  "address": {
    "line1": "The Value"
  }
}]

Outputs

The request will output the status and body that it receives back in the response. The status is the HTTP status code (usually 200 for a successful request) and the body is the content that the server returns.

If the request results in a status code of 500 or higher (or the request can't complete), it will be marked as failed in the logs and the flow stopped.

If your request returns structured data (either JSON or XML), it will be contained in the data output. This is a special data output type, and you should refer to the documentation for help using it.

Troubleshooting

There are lots of tools available that can help you to mimic, intercept and capture HTTP requests so you can understand and fix problems, here's a couple of them:

  • RequestBin (Pipedream) - a good place to send your requests to whilst testing (to check the format).
  • Postman - a Chrome app that helps you to send test webhooks.

Let us know how we can improve Flow XO on our feedback site.

Still need help? Contact Us Contact Us