# Workflows

Workflows allow you to trigger automation within Stampede by sending an incoming event. This is useful for pushing external event data — such as a customer action in a third-party system — directly into a Stampede workflow, so it can drive marketing, loyalty, or operational automations.

## Send an incoming event

<mark style="color:green;">`POST`</mark> `/v1/workflows/incoming-event`

#### Request Body

| Name                                                             | Type      | Description                                                                                                                                                                                          |
| ---------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| serials                                                          | String\[] | (Optional) One or more venue serial identifiers (max 12 characters each) to associate with the event                                                                                                 |
| parameters                                                       | Object    | (Optional) Arbitrary key-value payload with scalar values that will be passed into the workflow. Use the `source` key to direct the event to a specific workflow (e.g. `{"source": "some_service"}`) |
| organisation\_registration\_id<mark style="color:red;">\*</mark> | UUID      | The organisation registration ID (UUID format) that the event belongs to                                                                                                                             |

{% tabs %}
{% tab title="200: OK" %}

```typescript
{
  message: string
  event: object
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```typescript
{
  message: string
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```typescript
{
  message: string
  errors: Record<string, string[]>
}
```

{% endtab %}
{% endtabs %}

### Examples

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location 'https://global.stampede.ai/v1/workflows/incoming-event' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
    "serials": ["XXXXXXXXXXXX"],
    "organisation_registration_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parameters": {
        "source": "some_service",
        "key": "value"
    }
}'
```

{% endtab %}

{% tab title="NodeJs - Axios" %}

```javascript
const axios = require('axios')

const data = JSON.stringify({
  serials: ['XXXXXXXXXXXX'],
  organisation_registration_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  parameters: {
    source: 'some_service',
    key: 'value',
  },
})

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://global.stampede.ai/v1/workflows/incoming-event',
  headers: {
    'Content-Type': 'application/json',
    authorization: 'Bearer YOUR_ACCESS_TOKEN',
  },
  data,
}

axios
  .request(config)
  .then((response) => console.log(JSON.stringify(response.data)))
  .catch((error) => console.log(error))
```

{% endtab %}

{% tab title="PHP - Guzzle" %}

```php
<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'Bearer YOUR_ACCESS_TOKEN',
];
$body = '{
  "serials": ["XXXXXXXXXXXX"],
  "organisation_registration_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parameters": {
    "source": "some_service",
    "key": "value"
  }
}';
$request = new Request('POST', 'https://global.stampede.ai/v1/workflows/incoming-event', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```

{% endtab %}

{% tab title="Python - http.client" %}

```python
import http.client
import json

conn = http.client.HTTPSConnection("global.stampede.ai")
payload = json.dumps({
  "serials": ["XXXXXXXXXXXX"],
  "organisation_registration_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parameters": {
    "source": "some_service",
    "key": "value"
  }
})
headers = {
  'Content-Type': 'application/json',
  'authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
conn.request("POST", "/v1/workflows/incoming-event", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

{% endtab %}
{% endtabs %}

## Store a workflow run

<mark style="color:green;">`POST`</mark> `/v1/workflows/{workflowId}/workflow-runs`

Store a workflow run to push a user through a specific workflow, **regardless of whether they match the trigger conditions on that workflow**. This is useful for forcing workflow execution for specific users or scenarios without needing to satisfy the workflow's standard trigger requirements.

#### Path Parameters

| Name       | Type   | Description            |
| ---------- | ------ | ---------------------- |
| workflowId | String | The ID of the workflow |

#### Request Body

| Name         | Type | Description                                                         |
| ------------ | ---- | ------------------------------------------------------------------- |
| org\_reg\_id | UUID | The organisation registration ID (UUID format) for the workflow run |

#### Response

{% tabs %}
{% tab title="200: OK" %}

```typescript
{
  data: {
    id: string
    org_reg_id: string
    status: string
    profile: object
    trigger: string
    event: {
      triggered_by: string
    }
    nodes_processed: null | number
    created_at: string
    updated_at: string
  }
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```typescript
{
  message: string
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```typescript
{
  message: string
  errors: Record<string, string[]>
}
```

{% endtab %}

{% tab title="423: Locked" %}

```typescript
{
  message: string
}
```

The user is in the waiting period after previously triggering this workflow and cannot be triggered again yet.
{% endtab %}
{% endtabs %}

### Benefits over `incoming-event`

Using the **Store Workflow Run** endpoint provides several advantages over the standard `incoming-event` approach:

* **Guaranteed Execution**: Bypasses workflow trigger conditions, ensuring the workflow always executes regardless of event matching logic. Useful for manual overrides or special scenarios.
* **Direct Workflow Targeting**: Explicitly targets a specific workflow by ID, eliminating the need for event routing logic (e.g., using the `source` parameter to identify workflows).
* **Simplified Integration**: Requires minimal request payload (just `org_reg_id`), making it easier to implement for straightforward workflow execution scenarios.
* **Operational Control**: Ideal for internal operations, administrative actions, or system-triggered workflows where you need precise control over which workflow runs.

### Examples

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location 'https://global.stampede.ai/v1/workflows/{workflowId}/workflow-runs' \
--header 'Content-Type: application/json' \
--header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
    "org_reg_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}'
```

{% endtab %}

{% tab title="NodeJs - Axios" %}

```javascript
const axios = require('axios')

const data = JSON.stringify({
  org_reg_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
})

const config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://global.stampede.ai/v1/workflows/{workflowId}/workflow-runs',
  headers: {
    'Content-Type': 'application/json',
    authorization: 'Bearer YOUR_ACCESS_TOKEN',
  },
  data,
}

axios
  .request(config)
  .then((response) => console.log(JSON.stringify(response.data)))
  .catch((error) => console.log(error))
```

{% endtab %}

{% tab title="PHP - Guzzle" %}

```php
<?php
$client = new Client();
$headers = [
  'Content-Type' => 'application/json',
  'authorization' => 'Bearer YOUR_ACCESS_TOKEN',
];
$body = '{
  "org_reg_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}';
$request = new Request('POST', 'https://global.stampede.ai/v1/workflows/{workflowId}/workflow-runs', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```

{% endtab %}

{% tab title="Python - http.client" %}

```python
import http.client
import json

conn = http.client.HTTPSConnection("global.stampede.ai")
payload = json.dumps({
  "org_reg_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
})
headers = {
  'Content-Type': 'application/json',
  'authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
conn.request("POST", "/v1/workflows/{workflowId}/workflow-runs", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.stampede.ai/workflows/workflows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.