# Webhook

## Intro - What are Webhooks anyway?

![Webhook Helper](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/48103241944/original/B7es2aD5BwQYO8ZLfCEfRIDzT8mF2Z29NA.png?1620795900)

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

{% embed url="<https://www.youtube.com/watch?v=CT_1PJNonb4>" %}

## 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.&#x20;

<figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2Fjr3m66iF0SgtM0Iyia5k%2Fimage.png?alt=media&#x26;token=1a8690b3-399f-4b8c-8574-875d30bbe1ad" alt=""><figcaption></figcaption></figure>

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:

<figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2FkyDTHlSWbLECniQLQLBh%2Fimage.png?alt=media&#x26;token=8bdc7a47-7afd-4fc5-ad68-03b80d0e8a8a" alt=""><figcaption></figcaption></figure>

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.

{% hint style="info" %}
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.
{% endhint %}

Optionally for better security, you can use **Webhook Token**:

<figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2F6STm1Jueb7G97jPcLMJu%2Fimage.png?alt=media&#x26;token=aaea1442-2a6d-408d-854f-77205d8c0654" alt=""><figcaption><p>Webhook endpoint and security Bearer token</p></figcaption></figure>

#### 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:

```javascript
{
  "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:

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

{% hint style="info" %}
[Personal access tokens](https://docs.locoia.com/api/authentication-with-our-api) with scope `automation.webhook_run, automation.manage`, or `automation` can be used as an alternative to Flow-specific webhook tokens.
{% endhint %}

## 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`:

```javascript
{
   "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.&#x20;

`{{ 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**:

<figure><img src="https://291121471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McrRFZHYH27bqKzOVDd%2Fuploads%2FAzqMNMOAY6cCnMnpiYH0%2Fimage.png?alt=media&#x26;token=0e22ba73-26d2-4ffc-bbb7-f29358777a60" alt="" width="563"><figcaption><p>Webhook Settings example</p></figcaption></figure>

### Webhook response body example

You can include responses in your webhooks id Jinja2. A common response would look like this:

```python
{ 
  "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](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) 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