Search docs.molo17.com

    Events

    Events (also called trigger flows) let you fire on-demand chains of Gluesync actions from external systems via a simple HTTP call. Unlike scheduled jobs, events are not bound to a cron schedule — they are triggered by a POST request to a secret-protected endpoint.

    How-to guide

    For a step-by-step walkthrough tested on a running Gluesync, see the how-to guide Automate pipeline actions with schedules, chained events, and webhooks.

    Overview

    A trigger flow is a named, reusable definition of an ordered list of pipeline actions. It is conceptually identical to a scheduled job with chained events, but without the schedule: instead of running at a fixed time, it fires whenever an external caller POSTs to its trigger URL.

    Each trigger flow:

    • Has a human-readable name and optional description

    • Has an enabled flag to pause and resume the flow without deleting it

    • Carries a secret token used to authenticate incoming fire requests

    • Owns an ordered list of events (position 0-based) that execute sequentially when fired

    • Records last_triggered, last_successful_trigger, and last_error_message for observability

    • Exposes a stable trigger URL: POST /api/triggers/{id}/fire

    Typical use cases include:

    • CI/CD pipelines: fire a resync flow after each deployment

    • External orchestrators: trigger a stop-snapshot-start chain from n8n, Zapier, or a custom script

    • Manual operations: let an operator kick off a multi-step workflow with a single HTTP call

    • Platform events: automatically trigger a flow when a specific Core Hub event occurs

    How events differ from chained events

    Chained events (see Chained events) are bound to a scheduled job: they run after the parent job completes, on a fixed cron schedule. Events (trigger flows) use the same sequential execution engine but are fired on demand by an external HTTP call.

    Aspect Chained events Events (trigger flows)

    Trigger

    Cron schedule

    HTTP POST to a trigger URL

    Parent

    A scheduled job

    Standalone (no parent job)

    Authentication

    None (internal execution)

    Secret token in X-Trigger-Token header

    API prefix

    /api/jobs

    /api/triggers

    Both share the same event shape, execution modes, and supported actions.

    This includes the Query Studio action (task_type: query_studio) for both Core Hub platform events and incoming webhook requests. See Query Studio actions.

    Events can also start a published AI agent (task_type: ai_agent_run). See AI agent runs for payload interpolation, the 64 KiB fire-body limit, and AI run loop protection.

    Event fields

    Each event in a trigger flow specifies:

    Field Type Description

    task_type

    string

    Task to perform, such as pipeline_snapshot, entity_start, group_stop, pipeline_enter_maintenance, query_studio, or ai_agent_run

    pipeline_id

    string

    ID of the pipeline to operate on. Optional for ai_agent_run

    entity_ids

    array

    Entity IDs for entity-level operations

    group_ids

    array

    Group IDs for group-level operations

    with_snapshot

    boolean

    Whether to include a snapshot when starting or redoing

    snapshot_write_method

    string

    UPSERT or INSERT; applies to snapshot and redo actions

    execution_mode

    string

    async or sync

    agent_id

    string

    Required when task_type is query_studio

    query_sql

    string

    Custom SQL or saved-query snapshot when task_type is query_studio

    saved_query_id

    string

    Optional Query Studio saved query when task_type is query_studio

    query_read_only

    boolean

    Query Studio only. Defaults to true

    agent_alias

    string

    Required published agent alias when task_type is ai_agent_run

    agent_version

    integer

    AI agent run only. Optional published agent version

    prompt_template

    string

    AI agent run only. Optional prompt with allow-listed {{dotted.path}} tokens

    payload_allow_list

    array

    AI agent run only. Payload paths available for interpolation

    agent_input

    object

    AI agent run only. Optional input object; string values can contain allow-listed tokens

    idempotency_key

    string

    AI agent run only. Optional Core Hub idempotency key or template

    allow_ai_run_loop

    boolean

    AI agent run only. Allow the first AI run platform-event hop; defaults to false

    For the full list of supported actions and their mappings to task types, see Chained events.

    Execution modes

    Events support the same execution modes as chained events:

    Async

    In async mode, Chronos fires the action and immediately proceeds to the next event without waiting for it to complete. This is the fastest mode and is useful when later steps do not depend on the result of the previous one.

    Sync

    In sync mode, Chronos fires the event and waits for the Core Hub to confirm completion before proceeding to the next event. If the confirmation does not arrive within the configured timeout, the chain fails and the error is recorded on the trigger flow.

    Trigger flow sync events do not use the persistent webhook mechanism that scheduled chained events use. Instead, they fire one at a time and check the HTTP response. For the persistent webhook approach, see Chained events.

    API endpoints

    All trigger flow endpoints are under the /api/triggers prefix.

    Endpoint Method Description

    /api/triggers/

    GET

    List all trigger flows (paginated)

    /api/triggers/{id}

    GET

    Get a single trigger flow by ID

    /api/triggers/

    POST

    Create a new trigger flow

    /api/triggers/{id}

    PUT

    Update a trigger flow (events replaced atomically)

    /api/triggers/{id}/status

    PATCH

    Enable or disable a trigger flow

    /api/triggers/{id}

    DELETE

    Delete a trigger flow

    /api/triggers/{id}/regenerate-token

    POST

    Generate a new secret token

    /api/triggers/{id}/fire

    POST

    Fire a trigger flow

    Creating a trigger flow

    When you create a trigger flow, the response includes the secret token in plaintext. This is the only time it will be visible — store it safely. Subsequent GET requests return <redacted> as the token value.

    POST /api/triggers/
    
    {
      "name": "post-deploy-resync",
      "description": "Triggered after each production deploy via CI",
      "enabled": true,
      "events": [
        {
          "task_type": "pipeline_stop",
          "pipeline_id": "prod-pipeline",
          "execution_mode": "sync"
        },
        {
          "task_type": "pipeline_snapshot",
          "pipeline_id": "prod-pipeline",
          "with_snapshot": true,
          "snapshot_write_method": "UPSERT",
          "execution_mode": "sync"
        },
        {
          "task_type": "pipeline_start",
          "pipeline_id": "prod-pipeline",
          "execution_mode": "async"
        }
      ]
    }

    The response includes the secret_token and the trigger_url:

    {
      "id": 42,
      "name": "post-deploy-resync",
      "enabled": true,
      "secret_token": "sk_Jd8fkQ29Xm5...",
      "trigger_url": "http://chronos:8000/api/triggers/42/fire",
      "events": [...],
      "last_triggered": null,
      "created_at": "2026-07-14T10:05:00+00:00"
    }

    Firing a trigger flow

    To fire a trigger flow, send a POST request to its trigger URL with the X-Trigger-Token header:

    curl -X POST http://chronos:8000/api/triggers/42/fire \
      -H "X-Trigger-Token: sk_Jd8fkQ29Xm5..."

    By default, the endpoint returns 202 Accepted immediately and executes the chain in the background:

    {
      "trigger_flow_id": 42,
      "triggered_at": "2026-07-14T10:06:00+00:00",
      "status": "queued",
      "events_count": 3,
      "message": "TriggerFlow 'post-deploy-resync' queued for execution"
    }

    Synchronous fire (wait for completion)

    For CI/CD pipelines that need to know the outcome before continuing, pass wait=true:

    curl -X POST "http://chronos:8000/api/triggers/42/fire?wait=true&wait_timeout_seconds=300" \
      -H "X-Trigger-Token: sk_Jd8fkQ29Xm5..."

    The endpoint blocks until the chain finishes (or the timeout is reached) and returns the final status:

    {
      "trigger_flow_id": 42,
      "triggered_at": "2026-07-14T10:06:00+00:00",
      "status": "completed",
      "events_count": 3,
      "message": "TriggerFlow 'post-deploy-resync' completed"
    }

    Fire responses

    Status code Meaning

    202 Accepted

    Chain queued for background execution (wait=false, default)

    200 OK

    Chain completed synchronously (wait=true)

    401 Unauthorized

    Invalid or missing X-Trigger-Token header

    403 Forbidden

    Trigger flow is disabled

    404 Not Found

    Trigger flow ID does not exist

    500 Internal Server Error

    Execution error

    Token authentication

    Each trigger flow has a secret token generated at creation time using secrets.token_urlsafe(32). The token is:

    • Returned in plaintext only on creation and token regeneration

    • Never exposed in GET responses (returns <redacted>)

    • Verified using constant-time comparison to prevent timing attacks

    • Required in the X-Trigger-Token header for every fire request

    If a token is lost or compromised, use the regenerate-token endpoint to generate a new one. The old token is invalidated immediately.

    curl -X POST http://chronos:8000/api/triggers/42/regenerate-token

    Platform events

    Trigger flows can optionally be associated with a platform event — a Core Hub event type that automatically fires the flow when that event occurs. Set the platform_event field when creating or updating a trigger flow to the desired event type (for example, ENTITY_SNAPSHOT_COMPLETED or ENTITY_CDC_STARTED).

    When a platform event is configured, the trigger flow fires automatically whenever the Core Hub emits that event, without requiring an external HTTP call. This is useful for building reactive workflows such as:

    • Restarting CDC automatically after a snapshot completes

    • Triggering a follow-up snapshot when an entity starts

    • Running a maintenance flow when a pipeline enters maintenance mode

    The available platform event types match the Core Hub webhook event types. See Chronos webhooks for how Chronos uses them, and Enabled events for the full list.

    Using the Gluesync UI

    The Scheduler left nav is Schedules and Events only. There is no Webhooks item.

    Creating an event from the UI

    1. Navigate to Scheduler > Events.

    2. Click New.

    3. Choose Trigger type:

      • Platform event — required combo box of Core Hub types from GET /global-config/webhooks/event-types. Chronos stores the value as a free string.

      • Webhook trigger — incoming fire URL. After Save, a modal shows the secret token and trigger URL once. The URL is {origin}/chronos/api/triggers/{id}/fire. The tabs lock after the first save. You cannot change trigger type later.

    4. Fill in Enabled, Name, and an optional Description.

    5. Set one action (pipeline required; optional groups and entities). For a Query Studio action, select a saved query or enable Use a custom query and enter SQL. The Events form does not show execution mode, webhook timeout, or more than one action. Those controls belong to Schedules chained events.

    6. Click Save.

    Secret token and trigger URL appear only for Webhook trigger. The Platform event tab has neither.

    Managing events from the UI

    From the events table you can:

    • Fire now — Control Plane call (/fire-internal); no token

    • Enable / Disable — a disabled event rejects fire requests and skips platform-event callbacks

    • Regenerate token — webhook-trigger events only; invalidates the old token

    • Edit / Delete — trigger type cannot be changed after create

    • Expand a row for execution logs

    Sync wait and webhook timeout are on Schedules only. For how Chronos registers Core Hub callbacks, see Webhooks.

    Configuration

    The trigger URL is constructed from the following environment variables:

    Variable Description Default

    CHRONOS_CALLBACK_URL

    Base URL at which Chronos is reachable from external callers

    Derived from SCHEDULER_INTERNAL_HOST, PORT, and SSL_ENABLED

    SCHEDULER_INTERNAL_HOST

    Host used in the trigger URL when CHRONOS_CALLBACK_URL is not set

    localhost

    PORT

    Port used in the trigger URL when CHRONOS_CALLBACK_URL is not set

    8000

    SSL_ENABLED

    Whether HTTPS is used for the trigger URL

    False

    If CHRONOS_CALLBACK_URL is set, it takes precedence and is used directly as the base for all trigger URLs. This is useful when Chronos runs behind a reverse proxy or in a Docker network with a different hostname.

    curl examples

    Create and fire in one CI step

    # 1 — Create a trigger flow and capture the token
    TOKEN=$(curl -s -X POST http://chronos:8000/api/triggers/ \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "post-deploy-resync",
        "enabled": true,
        "events": [
          {"task_type":"pipeline_stop","pipeline_id":"prod","execution_mode":"sync"},
          {"task_type":"pipeline_start","pipeline_id":"prod","execution_mode":"async"}
        ]
      }' | jq -r '.secret_token')
    
    # 2 — Fire it from a CI step
    curl -X POST http://chronos:8000/api/triggers/1/fire \
      -H "X-Trigger-Token: $TOKEN"
    
    # 3 — Fire and wait for completion (useful in pipelines)
    curl -X POST "http://chronos:8000/api/triggers/1/fire?wait=true&wait_timeout_seconds=300" \
      -H "X-Trigger-Token: $TOKEN"

    Update a trigger flow’s events

    curl -X PUT http://chronos:8000/api/triggers/42 \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "post-deploy-resync",
        "enabled": true,
        "events": [
          {"task_type":"pipeline_stop","pipeline_id":"prod","execution_mode":"sync"},
          {"task_type":"pipeline_snapshot","pipeline_id":"prod","with_snapshot":true,"snapshot_write_method":"UPSERT","execution_mode":"sync"},
          {"task_type":"pipeline_start","pipeline_id":"prod","execution_mode":"async"}
        ]
      }'

    Disable a trigger flow

    curl -X PATCH http://chronos:8000/api/triggers/42/status \
      -H 'Content-Type: application/json' \
      -d '{"enabled": false}'

    Best practices

    • Store the secret token securely immediately after creation — it cannot be recovered later

    • Use wait=true with an appropriate timeout in CI/CD pipelines that need to gate on completion

    • Use sync execution mode when later events depend on the completion of earlier ones

    • Use async execution mode for independent steps that can run in parallel

    • Set CHRONOS_CALLBACK_URL when running behind a reverse proxy so trigger URLs are correct

    • Disable flows instead of deleting them when you need to temporarily pause automation

    • Regenerate tokens periodically or immediately if a token may have been exposed

    • Keep event chains short and focused on a single workflow

    • Test flows in a non-production environment before enabling them in production

    Troubleshooting

    Issue Possible cause Resolution

    Fire returns 401 Unauthorized

    Missing or incorrect X-Trigger-Token header

    Verify the token and ensure it is passed in the X-Trigger-Token header

    Fire returns 403 Forbidden

    Trigger flow is disabled

    Enable the flow via the UI or PATCH /api/triggers/{id}/status

    Trigger URL is unreachable

    CHRONOS_CALLBACK_URL not set or incorrect

    Set CHRONOS_CALLBACK_URL to the externally reachable URL of Chronos

    Chain stops early

    A sync event failed or timed out

    Check last_error_message on the trigger flow and the Chronos logs

    Token lost

    Token is only shown once at creation time

    Use POST /api/triggers/{id}/regenerate-token to get a new one

    Platform event not triggering

    Core Hub cannot reach the Chronos callback URL

    Verify network connectivity and CHRONOS_CALLBACK_URL configuration