Webhook
Triggering flows with webhooks
Last updated
Triggering flows with webhooks
Last updated
Webhooks are a way to trigger your flow in real time. Their basic purpose is Inter-App Communication: Webhooks are a modern method for applications to communicate with each other seamlessly. They enable one app to notify another app about changes or events. Also, they serve as a Notification Mechanism: Webhooks act like a "ping" or notification mechanism, allowing apps to say, "Hey, something has changed on my end, please take action." Webhooks can carry additional information (Payload Data) in JSON format, allowing you to transmit specific details about the change that occurred.
A webhook can be created for each flow if you drag & drop the Webhook Helper into the Flow Builder. A Webhook must always be the first step in your flow.
To trigger the flow we need a Webhook URL that can be seen in the Flow Settings.
1. You can get the URL by clicking the Edit settings button:
2. A Webhook URL looks like
https://api.locoia.com/v1/flow-webhook/{flow_id}
where {flow_id}
is replaced with your Flow's ID.
The rate limit for webhook requests is 300 requests from the same IP address (can be for multiple Flows) within a 5-minute window.
In case the rate limit is reached, you will receive a 429
status code with a Retry-After
header.
Optionally for better security, you can use Webhook Token:
Webhooks work on the flow status draft
or active
, 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:
For additional security, are enabled by default with a secret Bearer token that needs to be passed in the header in the form of:
Here Authorization is the header name, Bearer is the header type, which needs to be followed by an empty space, and then flowed by the secret token ey... which usually is a > 50 characters long and in this example only abbreviated with ey... .
Personal access tokens with scope automation.webhook_run, automation.manage
, or automation
can be used as an alternative to Flow-specific webhook tokens.
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
:
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 result in 123456
This allows you to pass any data you wish to Locoia.
The same applies for query parameters, e.g. `https://api.locoia.com/v1/flow-webhook/{flow_id}?value_1=123&value_2=test
:
Both request body and query parameters can be provided at the same time, however, in the Flow, one won't be able to differiantiate between them, as they will be in the same input dictionary.
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.
You can determine two webhook responses, the http status code and the actual response value:
You can include responses in your webhooks id Jinja2. A common response would look like this:
This returns res.value
if the request is true and otherwise valid: false in a JSON.
The response status code should be one of the three digit http status code numbers.
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.
All sync webhook requests will time out after 30 seconds and reply with a 408
status
Thus if the Flow takes longer than 30 seconds to run, it's result won't be part of the webhook response
The URL path cannot be extended or modified; in that case the request will receive a 404
status code response