Chained events

Chained events let you run a sequence of additional actions after a scheduled job completes. Use them to build multi-step workflows such as stopping a pipeline, running a snapshot, then restarting CDC.

Overview

A chained event is an extra task that is executed once the parent scheduled job finishes successfully. Each event specifies:

  • The action to perform (for example, start, stop, snapshot, redo, maintenance mode, Query Studio, or an AI agent run)

  • The target pipeline, group, or entity

  • The execution mode (async or sync)

  • An optional webhook timeout for sync events

Events are processed in order. If one event fails, the chain stops and the error is recorded on the parent job.

Execution Modes

Async

In async mode, Chronos fires the action and immediately proceeds to the next event without waiting for the action 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 registers a one-shot webhook in the Core Hub and waits for the previous action to complete before firing the next event. This is useful when later steps must run only after the previous step has finished successfully.

When a sync event is configured, Chronos:

  1. Registers a webhook in the Core Hub that listens for the completion event of the preceding step.

  2. Fires the chained event.

  3. Waits for the Core Hub callback.

  4. Proceeds to the next event once the callback is received or the configured timeout is reached.

The default webhook timeout is 3600 seconds (one hour). You can override it per event.

Supported Actions

Chained events support the same actions as scheduled jobs:

Action Maps to

Pause

entity_stop, group_stop, pipeline_stop

CDC

entity_start, group_start, pipeline_start

Snapshot with truncate

entity_snapshot, group_snapshot, pipeline_snapshot with INSERT

Snapshot without truncate

entity_snapshot, group_snapshot, pipeline_snapshot with UPSERT

Snapshot with truncate + CDC

entity_redo, group_redo, pipeline_redo with INSERT

Snapshot without truncate + CDC

entity_redo, group_redo, pipeline_redo with UPSERT

Put under maintenance

pipeline_enter_maintenance

Resume from maintenance

pipeline_exit_maintenance

Query Studio

query_studio; run a saved Query Studio query or custom SQL through an explicitly selected SQL-capable agent

AI agent run

ai_agent_run; start a published AI agent by alias

The target level (entity, group, or pipeline) is determined by the selected groups and entities, just like for regular scheduled jobs — except Query Studio, which is pipeline plus one SQL-capable agent only, and AI agent runs, which do not require a pipeline.

You can place more events after a Query Studio event. Query Studio has no Core Hub completion webhook: sync waits on the HTTP execute (120 seconds). If Query Studio is the preceding step, the next sync event skips the webhook wait. See Query Studio actions for query selection, write safeguards, and chained-event steps.

An AI agent run can also be a chained event. Use sync mode when a later action depends on the published agent completing successfully. See AI agent runs for the agent fields, safe payload interpolation, and loop safeguards.

Creating a Job with Chained Events

Chained events are part of the job payload when creating or updating a schedule via the REST API:

POST /api/jobs

{
  "name": "Nightly stop, snapshot, and restart",
  "task_type": "pipeline_stop",
  "cron_expression": "0 2 * * *",
  "pipeline_id": "pipeline-123",
  "enabled": true,
  "chained_events": [
    {
      "task_type": "pipeline_snapshot",
      "pipeline_id": "pipeline-123",
      "execution_mode": "sync",
      "webhook_timeout_seconds": 3600,
      "snapshot_write_method": "UPSERT"
    },
    {
      "task_type": "pipeline_start",
      "pipeline_id": "pipeline-123",
      "execution_mode": "sync",
      "webhook_timeout_seconds": 3600,
      "with_snapshot": false
    }
  ]
}

Each event in the chained_events array is executed in the order it appears. To clear chained events, pass an empty array in an update request.

Chained Event Fields

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

webhook_timeout_seconds

integer

How long to wait for a webhook callback in sync mode (default: 3600). Ignored when the preceding task is Query Studio (HTTP completion).

agent_id

string

Required when task_type is query_studio. SQL-capable agent.

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. false allows writes.

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.

Using the Gluesync UI

When you create or edit a schedule in the Gluesync UI, expand the Chained Events section and click Add event for each additional step.

For each event:

  1. Select the execution mode (Async or Sync).

  2. If Sync is selected, set the webhook timeout.

  3. Pick the action from the dropdown.

  4. Choose the target pipeline, group, or entity.

  5. For a Query Studio action, the target is pipeline-only. Select a saved query or enable Use a custom query and enter SQL, then confirm the SQL-capable agent.

  6. Use the up and down arrows to reorder events.

The number of chained events is shown in the section header so you can review the sequence at a glance.

How Sync Chains Work

When a job with sync chained events runs, Chronos opens an active listening window for the webhook callbacks. The Core Hub sends a callback when the preceding action completes, and Chronos uses that signal to proceed. If the callback does not arrive within the timeout, the chain fails and the error is recorded.

Chronos automatically registers the required webhooks when a job is created or updated, and cleans up orphaned webhooks at startup.

Best Practices

  • Use sync mode when the next step depends on the completion of the previous one

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

  • Set webhook timeouts long enough to cover the longest expected operation

  • Keep chains short and focused on a single workflow

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

  • Review the parent job’s last_error_message if a chain fails

Troubleshooting

Common Issues

Issue Possible Cause Resolution

Sync event times out

Preceding action took longer than the configured timeout

Increase webhook_timeout_seconds or check the Core Hub logs

Chain fails after an async event

The async action returned an HTTP error

Check the Chronos logs for the event ID and response

Webhook not received

Core Hub cannot reach the Chronos callback URL

Verify CHRONOS_CALLBACK_URL or network connectivity

Orphaned webhooks accumulate

Jobs were deleted without cleanup

Restart Chronos to trigger the stale webhook cleanup

See also