How workflows connect to Propeller
A workflow is a small automation that runs in a tool such as n8n. The examples in this library are built in n8n, but any software that exposes webhooks and can call an API works the same way. This page explains the two ways a workflow connects to Propeller and where its results show up. Read it once and every entry in the library will make sense.
Two directions
Embedded in Propeller. The workflow waits behind a webhook and Propeller calls it. This is how chat and button agents work: a user clicks the Workflows button on a page such as the quote editor, interacts with the agent and Propeller sends the request to your workflow. The workflow answers and the response appears in the panel.
Outside Propeller. The workflow runs on its own, for example on a schedule. It calls the Propeller API to read or change data and pushes its results into Propeller, for example as tickets in the Action Hub. Nobody has to click anything.
The building blocks
| Block | What it does | Where |
|---|---|---|
| API key | Lets your workflow read and change Propeller data | Admin > API Key Management, see API Keys |
| Agent | Connects an embedded workflow to a page in Propeller through its webhook URL | Admin > Agents, see AI Agents |
| Action Hub | Shows tickets that workflows and agents create, so sales reps can act on them | Sales > Action Hub, see Action Hub |
For an embedded agent, you paste your workflow's webhook URL into the agent configuration. The configuration also supports basic authentication and a signature salt to secure the connection.
How an embedded agent talks to your workflow
When a user interacts with an agent, Propeller sends a request to your webhook. The body contains the user's message as requestMessage and the context of the page as requestMetadata.payload, for example the quote the user is looking at.
Your workflow answers with a JSON response with three fields:
| Field | What it is |
|---|---|
conversationId | The id that ties the messages of one conversation together. See below |
responseMessage | The text shown to the user in the agent panel |
responseMetadata | Optional extra data, for example a processed flag and a timestamp |
Your workflow creates the conversation id
This is the part that surprises most builders. The first request of a conversation contains no conversation id, because the conversation does not exist yet. Propeller does not generate one for you. Your workflow generates it and returns it as conversationId in the response. Any unique string works. The library examples use a timestamp or the n8n execution id.
From then on, Propeller sends that id back as conversationId in the body of every follow-up request in the same conversation. Return the same id again so the conversation stays together.
So the rule is: reuse the conversation id from the request when there is one, generate one when there is not. In code that looks like this:
const conversationId = body.conversationId
|| body.requestMetadata?.conversationId
|| String(Date.now());
Every example in the library follows this pattern, so you can copy it from any entry.
What this means for the library
Every entry in the workflow library is labeled with where it runs:
- Embedded in Propeller entries need an agent configured in Admin > Agents pointing at your workflow.
- Outside Propeller entries need an API key and, when they create tickets, the Action Hub.
The install guide of each entry walks through the exact steps.