Workflow Trigger

Configure automatic workflow execution based on events, schedules, or webhooks.

Overview

The hyperfold workflow trigger command configures automatic workflow execution. Triggers define when workflows run—whether in response to events, on a schedule, or via external webhooks.

Workflows must be registered before triggers can be created. See workflow register to create workflows first.

Usage

# Trigger a workflow manually
$ hyperfold workflow trigger order-fulfillment \
  --input='{"order_id": "ord_123"}'

Triggering workflow: order-fulfillment
Input: {"order_id": "ord_123"}

✓ Workflow started
  Execution ID:     exec_abc123
  Status:           running

Watching execution... (Ctrl+C to detach)

[Step 1/4] validate_order
  ✓ Order ord_123 validated
  Duration: 120ms

[Step 2/4] reserve_inventory
  ✓ Inventory reserved for 2 items
  Duration: 340ms

[Step 3/4] create_shipment
  ✓ Shipment created: ship_xyz
  Duration: 2.1s

[Step 4/4] notify_customer
  ✓ Email sent to customer@example.com
  Duration: 450ms

✓ Workflow completed successfully
  Total Duration: 3.1s
  Output: {"shipment_id": "ship_xyz", "tracking": "1Z999..."}

Trigger Types

Type	Description	Flag
Event	Fire on system events (orders, inventory, etc.)	`--event`
Schedule	Fire on cron schedule	`--schedule`
Webhook	Fire on external HTTP POST	`--webhook`
Manual	Fire via CLI or API only	`--input`

Event and Schedule Triggers

# Trigger workflow on specific event
$ hyperfold workflow trigger cart-abandonment \
  --event=cart.abandoned \
  --filter='{"cart_value": {"$gt": 100}}'

Workflow trigger configured:
  Workflow:          cart-abandonment
  Event:             cart.abandoned
  Filter:            cart_value > 100
  Status:            active

# Trigger on schedule
$ hyperfold workflow trigger daily-inventory-sync \
  --schedule="0 6 * * *" \
  --timezone="America/Los_Angeles"

Scheduled trigger created:
  Workflow:          daily-inventory-sync
  Schedule:          Daily at 6:00 AM PST
  Next Run:          Tomorrow at 6:00 AM PST

# Trigger on webhook
$ hyperfold workflow trigger external-order \
  --webhook=true

Webhook trigger created:
  Workflow:          external-order
  Webhook URL:       https://api.hyperfold.io/webhooks/wf/ext_ord_xxx
  Secret:            whsec_xxx (use for signature verification)

Options

Option	Description
`--input`	JSON input for manual trigger
`--event`	Event name to trigger on
`--filter`	JSON filter for event conditions
`--schedule`	Cron expression for scheduled triggers
`--timezone`	Timezone for schedule (default: UTC)
`--webhook`	Create webhook endpoint trigger
`--transform`	Transform event data before passing to workflow
`--rate-limit`	Maximum trigger rate (e.g., "100/minute")
`--dedupe-key`	Field to deduplicate on
`--priority`	Execution priority (low, normal, high)

Examples

Managing Triggers

# List all workflow triggers
$ hyperfold workflow trigger list

WORKFLOW TRIGGERS

WORKFLOW                 TRIGGER TYPE    CONDITION                 LAST FIRED
order-fulfillment        event           order.created             2 min ago
cart-abandonment         event           cart.abandoned (>$100)    15 min ago
daily-inventory-sync     schedule        Daily @ 6:00 AM PST       6 hours ago
external-order           webhook         POST /webhooks/wf/...     1 hour ago
price-optimization       schedule        Hourly                    35 min ago
vip-customer-alert      event           customer.tier_upgraded    3 days ago

# Show trigger details
$ hyperfold workflow trigger show order-fulfillment

TRIGGER: order-fulfillment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Workflow:           order-fulfillment
Trigger Type:       event
Event:              order.created
Filter:             none
Status:             active
Created:            2025-01-15T10:00:00Z

EXECUTION STATS (30 days)
  Total Runs:       4,521
  Successful:       4,498 (99.5%)
  Failed:           23 (0.5%)
  Avg Duration:     3.2s

RECENT EXECUTIONS
  exec_789    order.created    ✓ success    3.1s    2 min ago
  exec_788    order.created    ✓ success    2.8s    5 min ago
  exec_787    order.created    ✓ success    4.2s    8 min ago
  exec_786    order.created    ✗ failed     1.2s    12 min ago
  exec_785    order.created    ✓ success    3.0s    15 min ago

Enabling/Disabling Triggers

# Disable a trigger temporarily
$ hyperfold workflow trigger disable order-fulfillment \
  --reason="Maintenance window"

Trigger disabled:
  Workflow:          order-fulfillment
  Reason:            Maintenance window
  Disabled at:       2025-01-20T10:00:00Z

⚠ Events matching this trigger will be queued (max 1000)

# Re-enable trigger
$ hyperfold workflow trigger enable order-fulfillment

Trigger enabled:
  Workflow:          order-fulfillment
  Queued events:     12

Processing queued events...
✓ 12 queued events triggered

# Delete a trigger
$ hyperfold workflow trigger delete cart-abandonment --confirm

✓ Trigger deleted
  Workflow remains but will not auto-trigger

Advanced Conditional Triggers

# Create conditional trigger with complex filters
$ hyperfold workflow trigger vip-order-alert \
  --event=order.created \
  --filter='{
    "$and": [
      {"customer.tier": {"$in": ["gold", "platinum"]}},
      {"order.total": {"$gt": 500}},
      {"order.items": {"$size": {"$gt": 3}}}
    ]
  }' \
  --priority=high

# Trigger with input transformation
$ hyperfold workflow trigger order-enrichment \
  --event=order.created \
  --transform='{
    "order_id": "{{event.order.id}}",
    "customer_email": "{{event.order.customer.email}}",
    "items": "{{event.order.line_items | map: \"sku\"}}",
    "priority": "{{event.order.total > 1000 ? \"high\" : \"normal\"}}"
  }'

# Rate-limited trigger
$ hyperfold workflow trigger price-check \
  --event=competitor.price_change \
  --rate-limit="100/minute" \
  --dedupe-key="product_id" \
  --dedupe-window="5m"

Common Events

Event	Description
`order.created`	New order placed
`order.fulfilled`	Order shipped
`cart.abandoned`	Cart inactive for threshold period
`inventory.low`	Inventory below threshold
`negotiation.completed`	Price negotiation finished
`customer.tier_upgraded`	Customer loyalty tier changed

Need to modify workflow behavior? See workflow update to change workflow definitions.

Search Documentation