# Workflows

Workflows automate actions in response to events. When something happens in your platform — a player deposits, a KYC check completes, a webhook arrives — a workflow can trigger a chain of actions automatically.

## How workflows work

Every workflow follows a **trigger, condition, action** pattern:

1. **Trigger** — An event occurs (e.g. `entity_event.transaction`, `provider.webhook.payment_intent.succeeded`)
2. **Condition** — Optional rules evaluate whether to proceed (e.g. "only if amount > 100")
3. **Action** — One or more steps execute (e.g. call a KYC provider, send a notification, update a state)

## Event types that can trigger workflows

| Event pattern | When it fires |
|---|---|
| `entity.created` | A new entity is created |
| `entity.updated` | An existing entity is updated |
| `entity.deleted` | An entity is soft-deleted (GDPR) |
| `entity_event.transaction` | A transaction event is recorded |
| `entity_event.game_activity` | A game activity event is recorded |
| `entity_event.session` | A session event is recorded |
| `entity_event.bonus` | A bonus event is recorded |
| `entity_event.block` | A block event is recorded |
| `entity_event.support` | A support event is recorded |
| `entity_event.affiliate` | An affiliate event is recorded |
| `entity_state.updated.<key>` | A state snapshot is updated (e.g. `entity_state.updated.kyc_status`) |
| `provider.webhook.<type>` | An inbound webhook is received from a provider |
| `gateway.request.completed` | A gateway call succeeded |
| `gateway.request.failed` | A gateway call failed |

## Common patterns

### When a player deposits, run a KYC check

**Trigger:** `entity_event.transaction`
**Condition:** `data.type == "deposit" && data.amount >= 100`
**Action:** Call KYC provider via gateway (`applicant.verify`)

### When KYC status changes, notify the team

**Trigger:** `entity_state.updated.kyc_status`
**Condition:** `value == "failed"`
**Action:** Send a notification via webhook delivery

### When a Stripe payment succeeds, update the player balance

**Trigger:** `provider.webhook.payment_intent.succeeded`
**Condition:** None
**Actions:**
1. Record a `transaction` event for the player
2. Update the player's `balance` state

### When a player's risk score changes, apply restrictions

**Trigger:** `entity_state.updated.risk_score`
**Condition:** `value == "high"`
**Action:** Call responsible gaming provider via gateway

## Triggering your workflow

You've built a workflow — how do you make it actually fire? There are four ways, from simplest to most production-ready.

### 1. Manual test run (testing only)

The fastest way to see your workflow execute. No external setup required.

1. Open your workflow in the editor
2. Click the **More menu** (kebab icon, top right) → **Run (test)**
3. The dialog pre-fills a sample JSON payload based on your trigger's event type. Edit it if needed.
4. Tick **"I understand this will make real API calls"** — test runs are live, not dry runs
5. Click **Run test**

Results appear inline in the dialog AND as colored statuses on each node in the canvas. The run also appears in the **Runs** tab at the bottom of the editor.

::: warning
Test runs make REAL API calls. If your workflow sends emails, charges cards, or modifies external data — it will actually happen. Use test data in the payload.
:::

### 2. Inbound webhook (easiest for production)

An external system POSTs JSON to a unique URL, and your workflow fires automatically. No code required on your side — just paste the URL into the sending system's webhook settings.

**Setup:**

1. Add a **Webhook Trigger** node to your workflow (drag from the Triggers category)
2. Click the node — a unique **Inbound URL** appears in the config drawer (e.g. `https://api.onehazel.com/webhook-receiver/wh_xxx`)
3. Click the copy button to copy the URL
4. **Save** the workflow and set it to **Active**
5. Paste the URL into the external system (Stripe webhook settings, GitHub webhook config, Slack outgoing webhook, Zapier, etc.)

**Test it with curl:**

```bash
curl -X POST https://api.onehazel.com/webhook-receiver/wh_YOUR_ID \
  -H "Content-Type: application/json" \
  -d '{"playerId": "player_123", "amount": 150, "currency": "EUR"}'
```

The webhook returns `202 Accepted` immediately — the workflow executes in the background. Check the **Runs** tab for execution results.

**Optional HMAC verification:** Set a `Verification Secret` in the webhook trigger config. The sending system must include an `X-OneHazel-Signature` header with an HMAC-SHA256 of the request body. Requests without a valid signature are rejected with `401`.

### 3. Schedule (cron)

The workflow fires automatically on a recurring schedule. Good for monitoring, reporting, and batch jobs.

**Setup:**

1. Add a **Schedule** node to your workflow
2. Set the **cron expression** (e.g. `0 9 * * *` for daily at 9am, `*/5 * * * *` for every 5 minutes)
3. Set your **timezone** (e.g. `Europe/Malta`) — the cron is evaluated in this timezone, not UTC
4. **Save** and set the workflow to **Active**

The system checks every minute. When the cron matches, the workflow fires.

**Common cron expressions:**

| Expression | Meaning |
|---|---|
| `* * * * *` | Every minute (for testing) |
| `0 * * * *` | Every hour at :00 |
| `0 9 * * *` | Daily at 9:00am |
| `0 9 * * 1` | Every Monday at 9:00am |
| `30 8,17 * * *` | At 8:30am and 5:30pm daily |

### 4. Event-driven (production data pipeline)

The most powerful trigger — workflows fire automatically whenever your backend pushes events through the OneHazel Data API. This is how production systems integrate.

**Setup:**

1. Add an **Event Trigger** node with the event type you want to listen to (e.g. `transaction`, `game_activity`, `session`)
2. **Save** and set the workflow to **Active**
3. From your backend, push events via the Data API:

```bash
curl -X POST https://api.onehazel.com/operator-data-api/entities/player_123/events \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "transaction",
    "data": {
      "type": "deposit",
      "amount": 150,
      "currency": "EUR"
    }
  }'
```

Every event insert automatically dispatches to the workflow engine. Any active workflow whose trigger event type matches will fire within ~1 second.

If the dispatch fails (engine cold start, network blip), the engine's scheduled-tick fallback picks up missed events within 60 seconds — giving at-least-once delivery.

**Supported event types:**

| Event type | Triggered by |
|---|---|
| `entity.created` | `POST /entities` |
| `entity_event.transaction` | `POST /entities/:id/events` with `eventType: "transaction"` |
| `entity_event.game_activity` | `POST /entities/:id/events` with `eventType: "game_activity"` |
| `entity_event.session` | `POST /entities/:id/events` with `eventType: "session"` |
| `entity_event.bonus` | `POST /entities/:id/events` with `eventType: "bonus"` |
| `state.updated` | `PUT /entities/:id/state/:key` |

### Which trigger should I use?

| Use case | Recommended trigger |
|---|---|
| Quick testing | Manual test run |
| Receiving events from Stripe, GitHub, Slack, etc. | Webhook trigger |
| Daily/hourly reports, monitoring, cleanup jobs | Schedule trigger |
| Reacting to your own backend events in real-time | Event-driven trigger |
| Multiple triggers on one workflow | Add multiple trigger nodes — any one can fire the workflow |

## Visual workflow builder (V3)

The OneHazel dashboard includes a visual workflow builder powered by a graph-based execution engine.

### Features

- **Drag-and-drop** canvas with 22 built-in node types across 6 categories
- **Auto-layout** using dagre for clean graph visualisation
- **AI chat** — describe what you want in natural language and the AI generates or modifies the workflow graph
- **Undo/redo** with keyboard shortcuts
- **Context menus** for quick node actions
- **Drop-to-connect** — drag a node near another to automatically create an edge

### Node categories

| Category | Node types |
|---|---|
| Triggers | Event trigger, schedule trigger, webhook trigger |
| Conditions | If/else, switch, filter |
| Actions | Gateway call, HTTP request, data transform |
| Data | Entity lookup, state read/write, event emit |
| Flow | Delay, loop, parallel, merge |
| Output | Notification, webhook delivery, log |

### V3 graph model

Workflows use a graph-based execution model where nodes and edges define the flow. The graph supports branching, parallel execution, and convergence. Workflows are stored with their graph structure and can be exported/imported.

## Templates

OneHazel provides pre-built workflow templates for common iGaming patterns. Templates are generated by the `WorkflowTemplateAgent` and can be customised after installation.

Browse templates in the workflow builder by clicking **Templates** in the sidebar.

## API

Workflows are managed through the OneHazel dashboard. The workflow engine (`workflow-engine` Edge Function) handles execution — it evaluates triggers, conditions, and actions using both V2 (flat steps) and V3 (graph) execution paths.

## Next steps

- Open the [workflow builder](https://app.onehazel.com) in the dashboard to create your first workflow
- See [Data Ingestion](/data-ingestion/) for the events that trigger workflows
- See [Gateway](/api-reference/gateway) for calling supplier APIs from workflow actions
- See [Webhooks](/api-reference/webhooks) for receiving events from external providers