Cron Chains
Chain multiple cron jobs into sequential workflows with conditional execution logic. Build deployment pipelines, data processing workflows, and automated run-books.
How Chains Work
A chain is an ordered sequence of steps, where each step executes an existing cron job. Steps run sequentially, and each step can be configured to run based on the previous step's outcome:
| Condition | Behavior |
|---|---|
on_success | Run only if the previous step succeeded (default) |
on_failure | Run only if the previous step failed |
always | Run regardless of the previous step's outcome |
Trigger Types
| Type | Description |
|---|---|
schedule | Runs automatically on a cron schedule |
manual | Triggered on-demand via dashboard or API |
webhook | Triggered by an incoming webhook to a linked endpoint |
Base URL
https://api.hookwatch.dev/v1/cron/chainsThe Chain Object
Properties
| Field | Type | Description |
|---|---|---|
id | string | Unique chain identifier |
name | string | Human-readable chain name |
description | string | Optional description |
trigger_type | string | How the chain is triggered: schedule, manual, or webhook |
trigger_schedule | string | Cron expression (required when trigger_type is schedule) |
trigger_endpoint_id | string | Webhook endpoint ID (when trigger_type is webhook) |
is_enabled | boolean | Whether the chain is active |
The Step Object
Step Properties
| Field | Type | Required | Description |
|---|---|---|---|
cron_job_id | string | Yes | ID of the cron job to execute |
step_order | number | Yes | Execution order (0-based) |
condition_type | string | No | When to run: on_success (default), on_failure, or always |
timeout_seconds | number | No | Max execution time in seconds (default: 3600) |
Create Chain
Create a new chain with its steps.
POST /v1/cron/chainsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name for the chain |
description | string | No | Optional description |
trigger_type | string | Yes | Trigger mode: schedule, manual, or webhook |
trigger_schedule | string | No | Cron expression (required if trigger_type is schedule) |
steps | array | Yes | Ordered list of steps to execute (see step fields below) |
Example
List Chains
Retrieve all chains for the authenticated user.
GET /v1/cron/chainsGet Chain
Retrieve a specific chain by ID.
GET /v1/cron/chains/:idUpdate Chain
Update a chain's metadata and optionally replace all steps. If steps is provided, all
existing steps are deleted and replaced.
PUT /v1/cron/chains/:idDelete Chain
Delete a chain and all its steps.
DELETE /v1/cron/chains/:idWarning
This action is irreversible. All steps associated with this chain will also be deleted.
Run Chain
Manually trigger a chain execution. Creates a new execution record starting from the first step.
POST /v1/cron/chains/:id/runThe Execution Object
Execution statuses:
running— Currently executingcompleted— All steps finished successfullyfailed— A step failed and no subsequent steps could runcanceled— Manually canceled by user
List Executions
Get execution history for a chain (paginated, newest first).
GET /v1/cron/chains/:id/executionsQuery Parameters
| Field | Type | Description |
|---|---|---|
limit | number | Max executions to return (default: 20, max: 100) |
offset | number | Number of executions to skip |
Response
Get Execution
Retrieve a specific execution by ID.
GET /v1/cron/chain-executions/:idCancel Execution
Cancel a running execution. Only works if status is running.
POST /v1/cron/chain-executions/:id/cancelError Codes
| Status | Error | Description |
|---|---|---|
400 | Bad Request | Missing name, invalid trigger type, or empty steps |
401 | Unauthorized | Invalid or missing access token |
404 | Not Found | Chain or execution not found |
409 | Conflict | Cannot cancel a non-running execution |