Webhook

Triggering flows with webhooks

Intro - What are Webhooks anyway?

Webhook Helper

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.

How do webhooks work?

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:

Webhook endpoint and security Bearer token

Flow statuses of Flows using webhooks

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:

{
  "status": 200,
  "error": "biz_logic",
  "message": "Flow status is `paused`. Unpause to run this flow using a webhook",
  "data": null
}

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 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.

Using Webhook request query and 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 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:

{
   "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.

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 example

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.

Limitations

• 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