Webhook

Intro - What are Webhooks anyway?
Webhook Helper
Webhooks are the most common, modern way of apps to interact with each other and tell each other that something has changed. So it is kind of a ping, "hey, please do something something changed on my end". E.g. a user profile has updated in your own backend application and you want another SaaS application, like e.g. Salesforce, to change the user details of that particular user in their app. In this case, you would create a webhook in the  app (Salesforce) and include it in your own backend application in a way that whenever a user is updated in your own system, it also pings Salesforce that an update occurred. A webhook can however not only notify about a particular resource, but also pass on information in the form of JSON in its so-called body.
How do webhooks work?
A webhook can be created for each flow if you drag & drop the webhook icon at the beginning of the flow to the workspace. If you now either click on the status button or the Edit button, you see the webhook URL to trigger the particular webhook which looks like this e.g. 
https://api.locoia.com/v1/flow-webhook/*some id* where *some id* is replaced with your flow's id. How you can get the URL easily is described below?
The easiest way to get the webhook URL and the Bearer token is by clicking on the edit button in the Flow Builder.
1. Click `Edit`
How to get to the Webhook endpoint and security Bearer token of a flow
2. Get the Webhook-Endpoint for your specific flow and the secret Bearer token to secure it.
Webhook endpoint and security Bearer token
Flow statuses of flows using webhooks
Webhooks work on the flow status `draft` or `live`, but they don't work on status `paused`. Use status `paused` if you want to disable webhook usage from someone triggering it externally. The flow will in this case return the following response and the webhook request will not be stored in the flow debugger:
{
  "status": 200,
  "error": "biz_logic",
  "message": "Flow status is `paused`. Unpause to run this flow using a webhook",
  "data": null
}
JavaScript
Webhook security Bearer token
For additional security, are enabled by default with a secret Bearer token that needs to be passed in the header in the form of:
Authorization: Bearer ey...
Here Authorization is the header name, Bearer is the header type, which needs to be followed by an empty space, and than flowed by the secret token ey... which usually is a >50 characters long and in this example only abbreviated with ey... .
Using Webhook request body data
If you send a request body in your POST request to a webhook, you can use the data in your flow. E.g. let's assume you send the following request body in your webhook's body as part of the POST request and the webhook has the ref-id `web1`:
{
   "company_id": 123456
   "user_id": 789123
}
You can access those variable with a combination of the ref-id and the keys of the request body e.g. 
{{ web1.company_id }} will yield 123456
This allows you to pass any data you wish to Locoia.
Supported content types
If the webhook request has the content types "application/xml" or "text/xml", the request body is expected to be in XML format and will be automatically converted to JSON format, so that it can be used in the flow.
For all other content types (or no content type), the Webhook Helper expects either a JSON or form-data as a request body, both will be shown in JSON format in the input of the webhook.
Webhook responses body
You can determine two webhook responses, the http status code and the actual response value:
Webhook Settings
Webhook response body example
You can include responses in your webhooks id Jinja2. A common response would look like this:
{ 
  "valid":
    {% if res1.value == "myResult" %} 
      "{{ res1.value }}"
    {% else %} 
      false
    {% endif %}
}
This returns res.value if the request is true and otherwise valid: false in a JSON.
Webhook http status code
The response status code should be one of the three digit http status code numbers.
Async Webhook
You can decide whether a flow triggered by a webhooks should run asynchronously, which means that the webhook will immediately send a response to the webhook sender and will then schedule the flow to run within the next 45 seconds (usually it will run within the next few seconds). You can use this option, in case the webhook sender does not expect a response that is based on the flow output, but rather just a 200 status code. This will make the response instantly and thus the webhook sender does not need to wait for a response until the flow is completed.
In case the webhook sender does expect flow output to be sent in the response, you cannot use the async option.

Scheduler

Dict Helper

Last modified 3mo ago

Copy link

Outline

Intro - What are Webhooks anyway?

How do webhooks work?

Webhook security Bearer token

Using Webhook request body data

Supported content types

Webhook responses body

Webhook response body example

Webhook http status code

Async Webhook