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.

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

See also