Triggers

A trigger is the entry point of every workflow. It determines when and how the workflow starts, and what initial data ({{trigger.output}}) it receives.

Every workflow has exactly one Trigger node. Select the trigger type in the node inspector.

Manual runs are always available

The trigger type controls how a workflow starts automatically. You can always run any workflow manually from the canvas toolbar, the Workflows list, or WorkflowDetail — regardless of whether its trigger is Schedule, Webhook, or API Call.

Trigger Types

Manual Trigger

The simplest trigger — runs when you click Run ▶ in the canvas, the Workflows list, or WorkflowDetail.

How It Works

Click Run ▶ anywhere in the UI
A modal appears with a free-text input field
Type any text you want the workflow to receive
Click Execute
The workflow starts with {{trigger.output}} = whatever you typed

Via API

POST /api/v1/workflows/{workflow_id}/execute
Authorization: Bearer sk-tarx-YOUR_KEY
X-Project-ID: {project_id}
Content-Type: application/json

{
  "input": "Analyze this document for security vulnerabilities"
}

Response:

{
  "execution_id": "exec_abc123",
  "status": "pending"
}

Use Cases

Development and testing of workflows
On-demand runs by team members
Workflows that process ad-hoc text queries

Params Trigger

Like Manual, but with a structured input form. You define named parameters with types — the user fills them in before running.

Configuration

In the node inspector, add one or more Input Parameters:

Field	Description
Name	Parameter key (used in expressions as `{{trigger.paramKey}}`)
Label	Human-readable label shown in the run form
Type	`text`, `number`, `boolean`, `select`
Required	Whether the field must be filled before running

Referencing Params

Each param is available as {{trigger.<name>}} in downstream nodes:

param name: "customer_id"  →  {{trigger.customer_id}}
param name: "report_type"  →  {{trigger.report_type}}

How It Works

Click Run ▶ — a typed form appears instead of a free-text box
Fill in the parameter values
Click Execute
Each param value is available as {{trigger.<name>}} throughout the workflow

Default values

Each parameter can carry a default value, coerced to its declared type (number → number, boolean → true/false, array/object → parsed from JSON, otherwise text). Defaults are what seed {{trigger.<name>}} when a workflow is run without explicit values — this applies to both the Run ▶ button and runs started from Bridge. Give your params sensible defaults so the workflow has something to work with on a bare "run it".

Running from Bridge

When you ask Bridge to run a workflow (e.g. "execute the KVE/CVE Scanner"), it uses the trigger's default param values automatically — the same values the Run button would send. You can override them in natural language, e.g. "run the KVE/CVE Scanner with devices = ["fw-1","fw-2"]"; values you specify win over the defaults, and any params you don't mention keep their defaults. This works in both Safe and Auto confirmation modes, and the run shows a live execution panel in the chat.

Via API

Pass a JSON object of param name → value pairs in the params field:

POST /api/v1/workflows/{workflow_id}/execute
Authorization: Bearer sk-tarx-YOUR_KEY
X-Project-ID: {project_id}
Content-Type: application/json

{
  "params": {
    "customer_id": "cust_456",
    "report_type": "monthly"
  }
}

Use Cases

Internal tools with structured inputs (customer ID, date range, report type)
Workflows shared with less-technical teammates who need a clear form
Automations triggered by other systems that pass structured data

Schedule Trigger

Runs the workflow automatically on a repeating schedule — no browser or human needed. The schedule runs on the server in UTC.

Setup

Set trigger type to Schedule in the node inspector.
Choose a frequency from the visual builder:
- Every N minutes — minimum 5 minutes
- Hourly
- Daily — pick a UTC time
- Weekly — pick days of the week + UTC time
- Monthly — pick day of month (1–28) + UTC time
- Custom — enter a raw cron expression
The generated cron expression is shown below the form.
Save the workflow — saving registers the schedule with the server.

Minimum interval: 5 minutes

Schedules more frequent than every 5 minutes are rejected. For near-real-time needs, use the Webhook or API Call trigger instead.

All Times Are UTC

The schedule runs in UTC regardless of your local timezone. Common conversions:

UTC Time	US Eastern	US Pacific	UK	Central Europe
`09:00`	5 AM (EST) / 4 AM (DST)	2 AM (PST) / 1 AM (PDT)	9 AM (GMT) / 10 AM (BST)	10 AM (CET) / 11 AM (CEST)
`14:00`	10 AM (EST)	7 AM (PST)	2 PM (GMT)	3 PM (CET)
`17:00`	1 PM (EST)	10 AM (PST)	5 PM (GMT)	6 PM (CET)

Common Schedule Examples

Frequency	Generated Cron	Description
Every 15 minutes	`/15 * * *`	Every 15 min
Hourly	`0 * * * *`	Top of every hour
Daily at 9 AM UTC	`0 9 * * *`	Every day, 9:00 UTC
Weekdays at 9 AM UTC	`0 9 * * 1-5`	Mon–Fri, 9:00 UTC
Every Monday at 9 AM UTC	`0 9 * * 1`	Weekly on Mondays
First of the month at 8 AM UTC	`0 8 1 * *`	Monthly

Trigger Output

Since no human provides input, the scheduled run starts with an empty {{trigger.output}}. Use a downstream Agent node to generate dynamic content (e.g., get today's date with datetime.now()).

Pausing Schedules

Toggle the Active state in the node inspector (or the workflow's enabled flag). Inactive schedules do not fire.

Restart-safe

Schedules persist across API restarts. All enabled schedules are re-registered automatically when the server starts.

Use Cases

Daily security log analysis
Weekly report generation
Hourly health monitoring
Monthly billing summaries
Nightly data processing

Webhook Trigger

An external service sends a POST request to your workflow's webhook URL to start it. Security comes from an HMAC-SHA256 signature — no login required.

The JSON payload is available as {{trigger.output}} in downstream nodes.

Setup

Set trigger type to Webhook in the node inspector.
Click Generate Webhook URL.
Copy the Webhook URL and Secret — the secret is shown once only.
Configure your external service to POST to the URL, signing requests with the secret.

Webhook URL Format

POST https://api.tarx.io/api/v1/webhooks/{workflow_id}

Signing Requests (HMAC-SHA256)

Every incoming request must include a signature header. The signature is HMAC-SHA256(secret, request_body):

import hmac
import hashlib
import json
import requests

secret = "your_webhook_secret"
payload = {"event": "user.created", "user_id": "u_123"}
body = json.dumps(payload).encode()

signature = hmac.new(
    secret.encode(),
    body,
    hashlib.sha256
).hexdigest()

requests.post(
    "https://api.tarx.io/api/v1/webhooks/{workflow_id}",
    headers={
        "Content-Type": "application/json",
        "X-TARX-Signature": f"sha256={signature}",
    },
    data=body,
)

Using curl:

SECRET="your_webhook_secret"
BODY='{"event":"user.created","user_id":"u_123"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "https://api.tarx.io/api/v1/webhooks/{workflow_id}" \
  -H "Content-Type: application/json" \
  -H "X-TARX-Signature: sha256=$SIG" \
  -d "$BODY"

Requests with invalid or missing signatures are rejected with 401 Unauthorized.

Keep your secret secure

The webhook secret is like a password — anyone with it can trigger your workflow. Store it in your sending service's secret manager, not in source code.

Response

Webhook responses are immediate (before execution completes):

{
  "execution_id": "exec_abc123",
  "status": "queued"
}

The workflow runs asynchronously. Poll GET /api/v1/executions/{execution_id} for results.

Rotating the Secret

If your secret is compromised:

Open the workflow on the canvas.
Click the Trigger node.
Click Rotate secret in the inspector.
Copy the new secret and update it in your sending service.

Brief downtime during rotation

Between rotating the secret and updating your sending service, incoming webhooks will fail with 401.

Common Webhook Sources

Service	Where to Configure
GitHub	Repository Settings → Webhooks → Add webhook
Stripe	Developers → Webhooks → Add endpoint
Linear	Settings → API → Webhooks
Slack	App configuration → Event Subscriptions
PagerDuty	Service → Extensions → Webhook
Custom apps	Any HTTP client that can compute HMAC-SHA256

Example: GitHub PR Review Automation

GitHub sends a pull_request webhook when a PR is opened. Use Payload Path $.pull_request.body to extract the PR description and feed it to a code review agent:

{
  "action": "opened",
  "pull_request": {
    "title": "Add user authentication",
    "body": "This PR adds JWT-based auth...",
    "html_url": "https://github.com/org/repo/pull/42"
  }
}

Triggering Any Workflow Programmatically

Every workflow — regardless of its trigger type — can be started via the API. There is no separate "API trigger" type; the execute endpoint is always available.

curl -X POST "https://api.tarx.io/api/v1/workflows/{workflow_id}/execute" \
  -H "Authorization: Bearer sk-tarx-xxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Project-ID: {project_id}" \
  -H "Content-Type: application/json" \
  -d '{"input": "optional input"}'

Use a Platform API Key (sk-tarx-...) for long-lived programmatic access — ideal for CI/CD pipelines, scripts, and services that need a non-expiring token. Generate one in Settings → Keys & Secrets → Platform API Keys.

See the API Overview for full endpoint documentation and auth options.

Trigger Types​

Manual Trigger​

How It Works​

Via API​

Use Cases​

Params Trigger​

Configuration​

Referencing Params​

How It Works​

Default values​

Running from Bridge​

Via API​

Use Cases​

Schedule Trigger​

Setup​

All Times Are UTC​

Common Schedule Examples​

Trigger Output​

Pausing Schedules​

Use Cases​

Webhook Trigger​

Setup​

Webhook URL Format​

Signing Requests (HMAC-SHA256)​

Response​

Rotating the Secret​

Common Webhook Sources​

Example: GitHub PR Review Automation​

Triggering Any Workflow Programmatically​

Trigger Types

Manual Trigger

How It Works

Via API

Use Cases

Params Trigger

Configuration

Referencing Params

How It Works

Default values

Running from Bridge

Via API

Use Cases

Schedule Trigger

Setup

All Times Are UTC

Common Schedule Examples

Trigger Output

Pausing Schedules

Use Cases

Webhook Trigger

Setup

Webhook URL Format

Signing Requests (HMAC-SHA256)

Response

Rotating the Secret

Common Webhook Sources

Example: GitHub PR Review Automation

Triggering Any Workflow Programmatically