Event Bus / Triggers

What it is

Triggers are the entry points that start a workflow. TurfAI has four: webhook, scheduled (cron), manual, and event sources via a unified Event Bus (push-based, starting with Google Drive folder watching and extensible to email/Slack). The Event Bus turns external events into workflow runs without polling, and writes every event to an audit log.

When to use it

• Webhook — start from an external system's HTTP POST (JSON, form-data, or file upload). Best when the other system already knows when something happened (a form was submitted, a record changed).
• Scheduled — recurring jobs (cron, timezone-aware). Best for time-driven work: nightly reports, weekly reminders, end-of-month reconciliation.
• Event source — react to "a file landed in this Drive folder". Best when you own the folder but not the upload event — TurfAI watches Drive for you.
• Manual — run on demand with custom JSON inputs. Best for testing and one-off backfills.

How it works

Process flow — event to execution:

Call flow — a Drive push trigger:

Sub-features

• Webhook — secret-key auth (timing-safe), file uploads, auto-generated curl samples, polling token, event-type tagging, secret rotation with a grace window, optional origin pinning.
• Scheduled — cron, timezone-aware, pause/resume (is_active), skip-if-running guard, next-run prediction.
• Event sources (Pub/Sub) — Drive folder watch, subscriptions with filters, event logs, auto watch renewal, volume stats.
• Manual — run with custom JSON inputs.

Configuration parameters

Webhook (api::webhook.webhook)

Scheduled (api::workflow-schedule.workflow-schedule)

Event source (api::event-source.event-source)

Event subscription (api::event-subscription.event-subscription)

Dependencies

• Event receiver endpoints in DMS (/api/event-bus/*, /api/webhooks/trigger/:id).
• Google Drive Watch API (for Drive event sources) + OAuth, plus a verified HTTPS domain for push.
• Job router / Redis + processors to execute the triggered workflow.
• Knowledge Base / RAG when auto_enable_rag is on — uploaded files are indexed there.

Limitations

• The unified Event Bus is an architecture/future-release design; Google Drive watching is the first source. Email and Slack sources are coming soon (the source_type enum already lists them).
• Webhook file uploads are bounded by max_file_size_mb (1–50) and allowed_mime_types.
• Google Drive watches expire (~24h) and are auto-renewed when expiry nears; a revoked OAuth grant stops renewal.
• Webhook payload size and request rate are capped (see the developer webhook guide).

Tips & best practices

• Choose the trigger by who knows about the event. External system knows → webhook. The clock knows → schedule. A Drive folder knows → event source.
• Renewals are automatic, but watch watch_expiry. A scheduler renews Drive watches before they lapse. If error_message is set or last_event_at is stale, re-authorize the source.
• Make workflows idempotent. Drive can deliver the same change more than once, and webhook callers may retry. Key your downstream writes on file_id / event_id so a duplicate trigger is a no-op.
• Filter at the subscription, not in the workflow. A filter like { "mime_type": "application/pdf" } or narrowing event_types to ["file_created"] avoids spinning up runs you'll just discard.
• Rotate webhook secrets without downtime. Rotation keeps previous_secret_key valid for the grace window so callers can deploy the new secret before the old one expires.
• Pin origins for browser-triggered webhooks. Set allowed_origins to your domains to reject calls from anywhere else.
• Pause, don't delete. Set is_active: false (schedule/source/subscription) or active: false (webhook) to keep counters and history.

Concrete examples

Cron syntax

Standard 5-field cron: minute hour day-of-month month day-of-week.

Always pair the cron with a timezone, e.g. Asia/Kolkata, so "9 AM" means 9 AM there — not UTC.

Webhook trigger payload + injected file variables

Trigger with a JSON body or multipart/form-data:

curl -X POST https://apisandbox.turfai.in/api/webhooks/trigger/1 \
  -H "X-Webhook-Secret: your_64_char_secret" \
  -F "resume=@candidate_resume.pdf" \
  -F "applicant_name=Jane Smith" \
  -F "email=jane@example.com"

Each uploaded file (field name resume) is injected into workflow inputs:

inputs.resume_document_id      // 789
inputs.resume_file_url         // "gs://turfdms/uploads/..."
inputs.applicant_name          // "Jane Smith"  (plain form fields pass through)
inputs._documents.resume       // { field_name, document_id, file_url, file_name, mime_type, file_size }
inputs._uploaded_files         // array of all uploaded files

Pattern: for a field named {field}, you get {field}_document_id and {field}_file_url, plus the structured _documents.{field} and the _uploaded_files array. The response also returns an execution_id and a short-lived polling_token.

Drive event source + subscription

# 1. Create the source (auto-registers a Drive watch)
curl -X POST https://apisandbox.turfai.in/api/event-sources \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "Invoices Folder", "source_type": "google_drive",
        "drive_item_id": "folder_123", "drive_item_type": "folder" }'

# 2. Bind a workflow, filtered to new PDFs
curl -X POST https://apisandbox.turfai.in/api/event-subscriptions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "PDF invoices", "event_source": 5, "activity": 123,
        "event_types": ["file_created"],
        "filter": { "mime_type": "application/pdf" } }'

Injected event inputs (Drive)

When a Drive event fires, the bound workflow receives:

{
  trigger_type: "event",
  event_id: "evt_abc123",
  event_source: "google_drive",
  event_type: "file_created",
  file_id: "abc123",
  file_name: "invoice.pdf",
  file_mime_type: "application/pdf",
  folder_id: "folder_123"
}

Reference these in nodes as {{file_id}}, {{file_name}}, {{file_mime_type}}, {{folder_id}}, and {{trigger_type}}.

Troubleshooting

How to test

Webhook

1. POST /api/webhooks with an activity id; copy the returned url and secret_key.
2. POST to that URL with X-Webhook-Secret and a JSON (or form-data) body — confirm a 200 with execution_id and polling_token.
3. Poll GET /api/workflow-executions/:id with the polling token until status: completed.

Schedule

1. Create a schedule with a near-future cron (e.g. */2 * * * *) and the correct timezone.
2. Confirm next_run_at is populated, then wait for last_run_at to update and run_count to increment.
3. Pause with is_active: false and confirm no further runs.

Drive event source + subscription

1. Create a google_drive event source for a folder you own; confirm watch_channel_id / watch_expiry are set.
2. Create a subscription binding a workflow, event_types: ["file_created"].
3. Drop a file into the folder; confirm an event-log entry (subscriptions_matched: 1) and a triggered run with the injected file_id / file_name inputs.

APIs used

Related

• Visual Workflow Builder — add a trigger node to a workflow canvas.
• Integrations — Google Drive OAuth and other connectors that back event sources.

Roadmap: Google Drive event sources are live today. Email and Slack event sources are coming soon — the same subscription + filter model will apply.