http

An http trigger is used to create a webhook and initiate a pipeline when a request is made to the webhook.

trigger "http" "my_webhook" {
  pipeline = pipeline.my_pipeline
  args     = {
    event = self.request_body
  }                              
}

It is common to pass in the request_body and/or request_header trigger attributes as arguments to the pipeline using self to reference the trigger instance.

Arguments

Argument	Type	Optional?	Description
`args`	Map	Optional	A map of arguments to pass to the pipeline.
`description`	String	Optional	A string containing a short description of the step.
`documentation`	String (Markdown)	Optional	A markdown string containing a long form description, used as documentation for the mod on hub.flowpipe.io.
`enabled`	Boolean	Optional	Enable or disable the trigger. A disabled trigger will not fire, but it will retain its history and configuration. Default is `true`.
`execution_mode`	String	Optional	Specifies whether the trigger should wait for the pipeline to complete and return its results in the response body (`synchronous`), or return immediately. The default is `asynchronous`,
`method`	method block	Optional	A supported HTTP http-methods block. The block label must be one of `get`, `post`. Note that if no `post` method block appears, only `post` is supported, and the top-level `pipeline`, `args`, and `execution_mode` apply.
`pipeline`	Pipeline Reference	Optional	A reference to a `pipeline` resource to start when this trigger runs.
`tags`	Map	Optional	A map of key:value metadata for the mod, used to categorize, search, and filter.
`title`	String	Optional	Display title for the step.

Attributes (Read-Only)

Attribute	Type	Description
`request_body`	String	The request body as a string.
`request_headers`	Map	A map of request header field names and values.
`status_code`	Number	The HTTP response status code.
`url`	String	The webhook URL.

HTTP Methods

By default, the http trigger will only fire on POST events. You can use method blocks to trigger different pipelines for different HTTP methods. The block label must be the method name (get or post).

Note that if no method blocks appear, only post is supported, and the top-level pipeline, args, and execution_mode apply.

trigger "http" "my_webhook" {

  method "post" {
    pipeline = pipeline.my_pipeline

    args = {
      event = self.request_body
    }
  }
    
  method "get" {
    execution_mode = "synchronous" 
    pipeline       = pipeline.confirm_setup

    args = {
      headers = self.request_headers
    }
  }
                              
}

Argument	Type	Optional?	Description
`pipeline`	Pipeline Reference	Required	A reference to a `pipeline` resource to start when this trigger runs.
`args`	Map	Optional	A map of arguments to pass to the pipeline.
`execution_mode`	String	Optional	Specifies whether the trigger should wait for the pipeline to complete and return its results in the response body (`synchronous`), or return immediately (`asynchronous`). The default is `asynchronous`,

Webhook Endpoint URL

Flowpipe creates an endpoint on the flowpipe server for each http trigger. The HTTP webhook does not support any authentication mechanism, but it does have a URL with randomness to make it unguessable. The webhook URL path is: /api/latest/hook/{trigger HCL label}/{random string}, eg /api/latest/hook/my_webhook/21ifp8truzi8y2r29jdl0qi7qt

The webhook URL will remain consistent across restarts. The {random string} is generated using the trigger name (the block label of the trigger ) and a global salt value.

Because the URL contains the trigger name, changing the trigger name will generate a new URL.
The salt value is stored in ~/.flowpipe/internal/salt
If the file is missing or empty, flowpipe will randomly generate a new salt and write it there. If you want to change all of your webhook URLs, remove the salt value.

Webhook Response

Flowpipe will return metadata in the response headers to identify the trigger process execution ID and the pipeline process execution ID:

Flowpipe-Execution-Id:          exec_cl92cgjjtoj4uv7etkq0
Flowpipe-Pipeline-Execution-Id: pexec_cl92cgjjtoj4uv7etkqg

If the HTTP trigger is configured to run a pipeline synchronously, it will return the outputs of the pipeline as top-level fields in the response. The response body will be formatted as JSON.

{
    "my_string_outout": "foo",
    "my_list_output": [
      "one",
      "two",
      "three"
    ],
    "my_object_output": {
      "color": "blue",
      "number": 34
    }
  }