# HTTP endpoint trigger
A HTTP trigger is a way for you to notify Bird about events that occur in an external system.
The HTTP trigger can trigger a flow that can operate in two modes:
* **Synchronous** - the flow will complete a process e.g. conditional logic and return a HTTP response and optional payload at the of the process
* **Asynchronous** - if the flow encounters any suspending step (e.g. wait, or send a message) the flow will return a HTTP 200 response before suspending and then the rest of the flow will process asynchronously
During the setup of a HTTP trigger, we'll generate a URL. This URL accepts GET/POST/PATCH/DELETE/PUT calls with JSON-formatted payloads, and a maximum size of 200KB
In addition you can optionally configure Bearer authorization with a shared secret key and also provide a shared secret to verify the request using HMAC-SHA256
## **Set up a HTTP endpoint trigger**
To set up a HTTP trigger, select the **HTTP endpoint** trigger type.
### **1. Configure authorization**
You can optionally add bearer token Authorization by specifying a secret key.
When you have added a secret key to you will need to make HTTP requests by setting the `Authorization` request header with value `Bearer mysecret`
### **2. Configure signature verification**
If you add an authorization key you can also optionally add HMAC-256 signature verification for your incoming request.
Firstly define the header that will contain the signature value e.g. signature and then add a shared secret for computing the HMAC-256 signature.
When you have added signature verification you will need to include this in your HTTP requests by setting the header key you have defined e.g. `signature` with value `sha256=signaturevalue`
### 3. Testing the HTTP trigger
When not using authorization and signature verification you can use the **Try it** function in the test section to send a sample payload to the flow trigger. Select the HTTP method you want to test with e.g `POST`
{% hint style="info" %}
If you have set up authorization and signature verification the Try it function will not be available and you will need to call the endpoint from a HTTP client as shown in the example below. You can copy the URL by clicking the copy button in the Test section as shown above
{% endhint %}
An example request would look as follows:
{% code overflow="wrap" %}
```bash
curl --location 'https://api.bird.com/workspaces/{{workspaceid}}/flows/{{flowid}}/invoke-sync?test-invocation=true' \
--header 'signature: sha256=dgXBMJxMCz02UW1unHPOTW9Rcc1i1+ZmXS1+xbWNWu0=' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"hello": "world"
}'
```
{% endcode %}
Finally click the button to update the test data and the the payload you sent should be included in the in test output. You can use this data later in the flow
## **Synchronous flow**
When triggering a HTTP flow that does not run an a suspending step (e.g. wait step or sending a message) the entire flow will complete a process and return a synchronous response. For example setting some variables from the incoming request body. By default the response will just be a `200` with an empty body, but you can optionally use the HTTP response step as the last step in the flow to return your own status code and request body.
An example of a synchronous flow is shown below:
## **Asynchronous flow**
When triggering a HTTP flow that does include a suspending step (e.g. a wait step) the flow will return a synchronous response before the suspending step. By default the response will just be a `200` with an empty body, but you can optionally use the HTTP response step before the suspending step to return your own status code and request body.
After the synchronous response, the flow will then continue to process asynchronously. An example of an asynchronous flow is shown below:
### **Cancelling an in-progress asynchronous flow**
The HTTP response before the flow starts processing asynchronously will contain a key called `Run-Id`. With this run ID you can make a `PATCH` request as follows to cancel an in-progress flow. You will need to make the request using a valid [access key](https://docs.bird.com/applications/settings/account/organization-settings/access-keys)
{% code overflow="wrap" %}
```bash
curl --location --globoff --request PATCH '{{baseUrl}}/workspaces/{{workspaceid}}/flows/{{flowid}}/runs' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"action": "cancel",
"ids": ["{{runid}}"]
}
```
{% endcode %}
## **Triggering a published flow**
After publishing a flow you can trigger this by making a HTTP request to the generated URL but be sure to remove the `?test-invocation=true` query parameter
