Triggers

Triggers automatically create workflow instances in response to external events. Four trigger types are supported: HTTP webhooks, NATS message queues, file-system watch events, and in-process event bus. All triggers are persisted to the database and managed via REST API.

HTTP webhook trigger

Register a webhook trigger with a secret, then send public delivery to POST /webhooks/{slug}. The raw JSON body becomes context.data. Public delivery is always signed; the authenticated /triggers/{slug}/fireroute is for trusted API clients and internal event invocation.

1POST /triggers
2{
3  "slug": "stripe_payment_failed",
4  "sequence_name": "payment_dunning",
5  "version": 1,
6  "tenant_id": "acme",
7  "enabled": true,
8  "secret": "whsec_your_signing_secret"
9}
10
11// Disable without deleting
12PATCH /triggers/stripe_payment_failed
13{ "enabled": false }

1POST /webhooks/stripe_payment_failed
2x-trigger-timestamp: 1787443200
3x-trigger-nonce: 7f6a2d85b1e94c31
4x-orch8-signature: v1=<base64url-hmac>
5
6signed_message = timestamp + "." + nonce + "." + raw_request_body
7signature = "v1=" + base64url(HMAC-SHA256(secret, signed_message))

Timestamps may be at most 300 seconds old or 60 seconds in the future. Nonces are single-use, 16–128 printable ASCII characters, and the body limit is 1 MiB. Sign the exact bytes sent—do not parse and re-serialize JSON after signing.

Transactional event-batch intake (current main)

PostgreSQL outbox producers can deliver up to 100 events per request toPOST /api/v1/events/batch. This endpoint is on current main after v0.7.1, not in the stable 0.7.1 release.

1{
2  "events": [{
3    "tenant_id": "acme",
4    "event_name": "order.completed",
5    "producer_event_id": "outbox-018f5d2f",
6    "correlation_key": "ORD-123",
7    "payload": { "order_id": "ORD-123" }
8  }]
9}

Retries with the same tenant, event name, andproducer_event_id are deduplicated. Keep the producer outbox row until the batch response confirms acceptance.

NATS message queue trigger

Subscribe to a NATS subject. When a message arrives, the engine creates a workflow instance. The message payload becomes context.data. Configure in orch8.toml.

1# orch8.toml — NATS trigger configuration
2[[triggers.nats]]
3subject = "events.payment.failed"
4sequence_name = "payment_dunning"
5tenant_id = "acme"
6url = "nats://nats-server:4222"
7
8# Multiple NATS triggers from different subjects
9[[triggers.nats]]
10subject = "events.user.signup"
11sequence_name = "welcome_onboarding"
12tenant_id = "acme"
13url = "nats://nats-server:4222"

The trigger processor loop syncs trigger definitions from the database at startup and dynamically starts/stops listeners when triggers are created or disabled via API.

File watch trigger

Watch a directory (or file path) for create and modify events. When the OS notifies of a change, the engine creates a workflow instance with the file path and event type in context.data. Uses the notify crate for cross-platform fs-event support.

1# orch8.toml — file watch trigger
2[[triggers.file_watch]]
3path = "/data/incoming"
4recursive = true
5sequence_name = "process_incoming_file"
6tenant_id = "acme"
7
8# context.data for each trigger:
9# { "path": "/data/incoming/report.csv", "event": "create" }
10
11# Combine with a processing sequence
12{
13  "type": "step", "id": "process_file",
14  "handler": "csv_importer",
15  "params": { "path": "{{context.data.path}}", "event": "{{context.data.event}}" }
16}

Event trigger (in-process event bus)

Event triggers use an in-process event bus for trusted server-to-server or in-cluster integration. Unlike webhooks, event triggers carry no HMAC validation. They can be fired via POST /triggers/{slug}/fire or internally by workflows using the emit_event built-in handler.

1POST /triggers
2{
3  "slug": "order_completed",
4  "sequence_name": "post_order_processing",
5  "tenant_id": "acme",
6  "trigger_type": "event",
7  "enabled": true
8}
9
10// Fire directly via API
11POST /triggers/order_completed/fire
12{ "order_id": "ORD-123", "total": 99.99 }

1// Or fire from another workflow step
2{ "type": "step", "id": "emit_order_event",
3  "handler": "emit_event",
4  "params": { "slug": "order_completed", "payload": { "order_id": "{{context.data.order_id}}" } } }

Trigger management API

1# List all triggers
2GET /triggers
3
4# Get a trigger by slug
5GET /triggers/{slug}
6
7# Update trigger
8PATCH /triggers/{slug}
9{ "enabled": false }
10
11# Delete a trigger
12DELETE /triggers/{slug}