# integration



# Integration

Use the `integration` block to configure how pipelines interact with an external system, such as Slack or Email, via [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) steps.

Like [triggers](/docs/build/triggers), integrations require callback endpoints, so they only work in [server-mode](/docs/run/server).  When you run a pipeline in [client-mode](/docs/run#operating-modes), notifications for [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) steps will only appear on the command line, regardless of your `notifier` and `integration` configuration.  To send [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) requests to your integrations, you must run [Flowpipe server](/docs/run/server)!


Integrations are *configuration* resources, defined in configuration files (`.fpc`), not mod files(`.fp`).  Here's why:
- The settings are installation-specific and may contain secrets.
- The settings are usually the same for *all* mods in a given installation.

Note that while the *definition* of the integration happens at the installation level, the *instantiation* is per Flowpipe process instance.  If, for example, you run 2 separate `flowpipe server` instances on the same host, they will both share the same Slack integration definition, but each will create its own instance, with its own URL.

An `integration` is similar in many respects to a `trigger`:
- It is loaded at mod start-up time and usually creates a public HTTP endpoint (the `request_url`).
- There are multiple types, each with its own label eg (`integration "slack" "my_slack`), and the arguments vary by type.

Unlike a `trigger`, an `integration` does not *initiate* a pipeline but instead is referenced *in a pipeline step* to interact with an external system.

## Request URL
Behind the scenes, each of these integrations has its own **Request URL** HTTP endpoint.  The integration endpoints will receive responses in their native format and will perform service-specific tasks — for security, authentication, data transformation, etc — to extract the `value` from the response.  The value will be passed as an attribute of the step so that it may be inspected by later steps. 

The Request URL enables external system to connect to Flowpipe. To avoid reconfiguring that external system, it's important to maintain a stable URL. In order to generate a consistent but unguessable URL path, the URLs are generated by hashing the trigger name with a salt.  The salt file is written to the Flowpipe install directory, in the `internal` subdirectory: `~/.flowpipe/internal/salt`.  

## Base URL
The Request URL must be publicly accessible in order for the external user or system to respond.  Flowpipe does not know the hostname portion of this URL, so you must provide it by setting the [Base URL](/docs/reference/env-vars/flowpipe_base_url) to a host that the recipient can route to.  This may include the DNS or IP address of the system on which you are running Flowpipe, or it may be a reverse proxy such as [ngrok](https://ngrok.com/). You can set the base URL via the [FLOWPIPE_BASE_URL](/docs/reference/env-vars/flowpipe_base_url) environment variable, the `base_url` [workspace argument](/docs/reference/config-files/workspace), or pass it via the `--base-url` argument to the [flowpipe server](/docs/reference/cli/server) command.  Typically, it's simplest to set it in your [default workspace](http://localhost:3000/docs/run/workspaces#using-workspaces):

```hcl
workspace "default" {
  base_url      = "https://84c5df474.ngrok-free.dev"
}
```