Event Bus

Use the Event Bus to start a workflow in response to an external event, not only from an explicit HTTP trigger. The first source is Google Drive folder watching; Gmail push (email) sources are also supported, and the model is unified and extensible (Slack event sources are coming soon).

Core model

Four pieces move an external change into a running workflow:

1. Event source — an external system that emits events: a watched google_drive folder, a Gmail mailbox, etc. It owns the watch channel and credentials. Created via POST /event-bus/sources.
2. Event — a normalized record the bus builds from the source's raw notification: source_type, event_type (e.g. file_created), a payload of source-specific fields, and a generated event_id. Every event is written to the event log (audit trail).
3. Subscription — links one event source to one workflow (activity), with the event_types and optional filter it cares about. No subscription, no trigger — the source only watches; the subscription is what fires a workflow.
4. Dispatch — for each matching subscription, the bus builds the workflow inputs from the event and queues a workflow execution (source: "event").

The Drive flow

Drive sends several notifications per upload. TurfAI settles the file (waits until version and size stop changing) and de-duplicates per (file_id, source) before publishing exactly one event, so a workflow fires once per file.

Create a Drive event source

TurfAI reads the owner's Google credentials from their connected integration, so you pass the folder, not tokens.

curl -X POST https://apisandbox.turfai.in/api/event-bus/sources \
  -H "Authorization: Bearer $TURFAI_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "google_drive",
    "folder_id": "1AbCfolderId",
    "folder_name": "Invoices"
  }'

{
  "success": true,
  "data": {
    "id": 12,
    "name": "Invoices",
    "source_type": "google_drive",
    "drive_item_id": "1AbCfolderId",
    "drive_item_type": "folder",
    "drive_item_name": "Invoices",
    "is_active": true,
    "watch_expiry": "2026-06-21T10:00:00.000Z"
  }
}

If the server's public HTTPS URL isn't configured at creation time, the source comes back with is_active: false (a pending watch). Activate it to register the real Drive push channel:

curl -X POST https://apisandbox.turfai.in/api/event-bus/sources/12/activate \
  -H "Authorization: Bearer $TURFAI_JWT"

{ "success": true, "data": { "id": 12, "is_active": true, "watch_expiry": "2026-06-21T10:00:00.000Z" } }

List sources (GET /event-bus/sources), read the audit trail (GET /event-bus/logs), and view aggregate stats (GET /event-bus/stats). Delete with DELETE /event-bus/sources/:id — this calls channels.stop() to tear down the Google watch.

Watch channel renewal and expiry

Google Drive push channels expire after at most 24 hours. TurfAI stores watch_expiry on the source, and an hourly scheduler automatically renews any watch expiring within ~2 hours, so an active source keeps firing without intervention. Gmail watches expire after 7 days.

If renewal fails, TurfAI marks the source is_active: false with an error_message, and notifications stop until you recreate or re-activate it. To force a renewal sweep, call POST /event-bus/renew-watches?force=true.

Event inputs in your workflow

When a Drive file is created, the dispatched workflow receives the event metadata plus the file payload as inputs:

{
  "trigger_type": "event",
  "event_id": "evt_a1b2c3d4",
  "event_source": "google_drive",
  "event_type": "file_created",
  "event_timestamp": "2026-06-20T10:00:00.000Z",

  "file_id": "1XyZdriveFileId",
  "file_name": "invoice-0420.pdf",
  "file_mime_type": "application/pdf",
  "file_size": "102400",
  "file_url": "gs://turfdms/uploads/...",
  "file_web_link": "https://drive.google.com/file/d/1XyZdriveFileId",
  "file_document_id": 789,
  "folder_id": "1AbCfolderId",
  "folder_name": "Invoices",
  "change_type": "created"
}

Reference these with {{file_id}}, {{file_name}}, etc. in downstream nodes — typically a google_drive_fetch (or the already-created file_document_id) followed by extraction and a notification. Other Drive event_types are file_modified, file_removed, and file_deleted.

Prerequisites

Drive watching requires:

• Connected Google access for the source owner (delegated OAuth — see Authentication); the Drive API enabled on the Google project.
• A public HTTPS endpoint with a valid certificate (Google won't push to http:// or localhost) and Google domain verification for push notifications.

Build it hands-on in Event-driven automation.

Reference

Event Bus API and the synced Google integrations quick start.