Task Triggers

Your compose tasks can be triggered by several different mechanisms. Triggers are configured in your manifest file for each task. Each task can have multiple triggers (one of each type), so triggers are configured as an array. Below is an overview of all the supported trigger types: cron, http, and onchain_event.

Local Task Execution

For locally testing tasks you can use the callTask CLI command. This works regardless of what trigger types a task has configured (and even for tasks with no triggers at all).

Trigger Task locally with CLI

goldsky compose callTask "my_task" '{ "foo": "bar" }' --env local

Task Code

import { TaskContext } from "compose";

type Payload = {
  foo: string;
};

export async function main({ collection }: TaskContext, payload: Payload) {
  // the task will be called with the payload sent from the CLI callTask command
  console.log(payload.foo);
}

Task To Task Execution

Tasks can call other tasks directly — no trigger configuration required on the called task. This is done using the callTask context function.

Example

import { TaskContext } from "compose";

type ProcessDataPayload = {
  dataId: string;
  operation: string;
};

export async function main({ callTask }: TaskContext, payload: ProcessDataPayload) {
  // Call another task with a payload
  const result = await callTask<{ success: boolean; processed: number }>(
    "process-data",
    {
      dataId: payload.dataId,
      operation: payload.operation,
    }
  );

  return {
    status: "completed",
    result,
  };
}

The process-data task will receive the payload and can return a response:

import { TaskContext } from "compose";

type ProcessDataArgs = {
  dataId: string;
  operation: string;
};

export async function main({ collection }: TaskContext, payload: ProcessDataArgs) {
  // Process the data based on the operation
  const processed = await collection("data").findMany({ id: payload.dataId });

  return {
    success: true,
    processed: processed.length,
  };
}

Chain Event Triggers

Tasks can be triggered by onchain events. The payload delivered to the task is the raw encoded log. Compose provides helpers for decoding the event in your task code — see Contracts for more details on decoding.

Onchain event triggers only fire when your app is deployed to the cloud. They do not fire during local development. To test a task with an onchain trigger locally, use callTask with a sample event payload:

goldsky compose callTask "my_task" '{"blockNumber":48758053,"address":"0xb74de3F91e04d0920ff26Ac28956272E8d67404D","data":"0x","topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"],"transactionHash":"0x2c50...","logIndex":343}' --env local

You can copy a real event payload from a block explorer to use as test data.

Example event object sent as the payload to your task:

{
  "blockNumber": 48758053,
  "blockHash":
    "0x6794a56583329794f184d50862019ecf7b6d8ba6b3210f68ca4b91a8fa81817d",
  "transactionIndex": 29,
  "removed": false,
  "address": "0xb74de3F91e04d0920ff26Ac28956272E8d67404D",
  "data": "0x",
  "topics": [
    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
    "0x0000000000000000000000000000000000000000000000000000000000000000",
    "0x000000000000000000000000eec2ba9b9f0202c63bba29ea9a4ce5c23f9865fd",
    "0x0000000000000000000000000000000000000000000000000000000000001099",
  ],
  "transactionHash":
    "0x2c500a55f5c24d587e73805975d91395634a971dca5939f43d34d774d0f7147b",
  "logIndex": 343,
}

Example configuration for an onchain event trigger:

name: "my-app"
tasks:
  - name: "on_transfer"
    path: "./tasks/on_transfer.ts"
    triggers:
      - type: "onchain_event"
        network: "base_sepolia"
        contract: "0xb74de3F91e04d0920ff26Ac28956272E8d67404D"
        events:
          - "Transfer(address,address,uint256)"

Task code

Here’s an example in which we decode the event with a contract class we’ve generated with goldsky compose codegen, see Contracts for more info.

import { TaskContext, OnchainEvent } from "compose";

// the payload for an onchain triggered task will always be our built in OnchainEvent interface
export async function main({ evm }: TaskContext, payload: OnchainEvent) {
  // we can decode the event with our ABI generated contract class
  // the type of this decodedEvent will be a union of all events that the ABI specifies, allowing you to conditionally process based on the eventName
  const decodedEvent = evm.contracts.MyNFT.decodeEventLog(payload);

  if (decodedEvent.eventName === "Transfer") {
    // in this code block typescript will know the decodedEvent is of type TransferEventDecoded
    // this pattern is useful when your trigger supports multiple event types
    console.log("Transfer event:", decodedEvent.args);
  }

  // alternative would be to cast, this is useful if your trigger is configured for a single event type
  const castEvent = evm.contracts.MyNFT.decodeEventLog<TransferEventDecoded>(payload);
}

Onchain Trigger Properties

Property	Type	Required	Description
`type`	`"onchain_event"`	Yes	Type discriminator
`network`	string	Yes	The network slug in snake_case (e.g. `base_sepolia`, `ethereum_mainnet`). See Chains for the full list.
`contract`	string	Yes	The contract address (`0x` followed by 40 hex characters).
`events`	string[]	No	Specific event signatures (human-readable, not encoded) to match — e.g. `"Transfer(address,address,uint256)"`. If omitted, all logs from the contract are delivered.
`dataset_version`	string	No	Override the dataset version for chains that don’t use `1.0.0` (e.g., `megaeth_testnet_v2`). If not specified, the server auto-detects the correct version.

Failure Handling

Onchain-triggered tasks honor the task’s retry_config. When a task throws (or otherwise fails), Compose retries it up to max_attempts with the configured backoff. If every attempt fails, that event is dropped and the pipeline advances to the next one — it is not replayed. This means an unhandled exception in an onchain-triggered task only stalls delivery for the duration of your retry window, not indefinitely. If you want a failure to be visible without consuming retries, catch the error in your task and return normally — the run is recorded as successful and the pipeline moves on.

Cron Triggers

Tasks can be triggered on a schedule. Tasks triggered by cron are invoked with an empty payload ({}), since each invocation is generic.

Example

name: "my-app"
tasks:
  - name: "hourly_sync"
    path: "./tasks/sync.ts"
    triggers: 
      - type: "cron"
        expression: "0 * * * *" # Every hour at minute 0

6-field (second-granularity) example

Pass a 6-field expression if you need second-level precision — the first field becomes seconds:

triggers:
  - type: "cron"
    expression: "*/30 * * * * *" # every 30 seconds

Cron Trigger Properties

Property	Type	Required	Description
`type`	`"cron"`	Yes	Type discriminator
`expression`	string	Yes	A cron expression. Supports both 5-field (`minute hour day month weekday`) and 6-field (`second minute hour day month weekday`) formats. Accepts ``, numbers, ranges (`1-5`), lists (`1,3,5`), and step values (`/2`).

HTTP Triggers

Tasks can be triggered by HTTP requests. This is often used to kick off compose tasks from your application logic. HTTP triggers accept any JSON payload you want for dynamic execution.

Example

name: "my-app"
tasks:
  - name: "status"
    path: "./tasks/status.ts"
    triggers:
      - type: "http"
        authentication: "auth_token" # other option is "none"

Http Trigger Properties

Property	Type	Required	Description
`type`	`"http"`	Yes	Type discriminator
`authentication`	`"auth_token" \| "none"`	Yes	Type of authentication to use on the endpoint.
`role`	`"Owner" \| "Admin" \| "Editor" \| "Viewer"`	No	The minimum RBAC role required to call the endpoint (only applies when `authentication` is `"auth_token"`). Defaults to `"Viewer"` (any team member).
`ip_whitelist`	string[]	No	Restrict access to specific IPs. Supports IPv4, IPv6, and CIDR notation (e.g. `["192.168.1.0/24", "10.0.0.1"]`).

Authenticated triggers require a Goldsky API token when the app is deployed, but can be called without auth when testing locally. Unauthenticated triggers can be called without auth both locally and when deployed.

Base URL

Locally, Compose runs on http://localhost:4000 by default. If port 4000 is taken, start picks the next free port up to 4009 and records it in .compose/.port. The base pattern for all task endpoints is:

http://localhost:4000/tasks/{taskName}

When deployed to the cloud, tasks with an authenticated HTTP trigger (authentication: "auth_token") are reachable at:

https://api.goldsky.com/api/admin/compose/v1/{appName}/tasks/{taskName}

When deployed to the cloud, tasks with an unauthenticated HTTP trigger (authentication: "none") are reachable at:

https://api.goldsky.com/api/public/compose/v1/{projectId}/{appName}/tasks/{taskName}

HTTP Request Format

curl -X POST http://localhost:4000/tasks/{taskName} \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

When deployed to the cloud with authentication: "auth_token", you’ll need to pass a Goldsky API token:

curl -X POST https://api.goldsky.com/api/admin/compose/v1/{appName}/tasks/{taskName} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"foo": "foo"}'

Execute HTTP trigger without parameters

curl -X POST http://localhost:4000/tasks/bitcoin-oracle \
  -H "Content-Type: application/json" \
  -d '{}'

Execute an HTTP trigger with parameters

curl -X POST http://localhost:4000/tasks/bitcoin-oracle \
  -H "Content-Type: application/json" \
  -d '{
    "contractAddress": "0x742d35Cc6634C0532925a3b8D6Ac6E7D9C3c1234",
    "threshold": 1000
  }'

Response Format

Tasks return JSON responses with the data returned by the task’s main function. Calling this task:

import { TaskContext } from "compose";

export async function main(_context: TaskContext, payload: { name?: string }) {
  const name = payload?.name || "World";

  return { success: true, greeting: `Hello, ${name}!` };
}

via this request:

curl -X POST http://localhost:4000/tasks/greeting \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Adam"
  }'

returns this JSON response:

{
  "success": true,
  "greeting": "Hello, Adam!"
}

Next Steps

Using Packages

You can use any sandbox compatible typescript packages with any package manager.

Debugging

Debug and monitor your apps

Compose

Guides

Reference

Local Task Execution

Trigger Task locally with CLI

Task Code

Task To Task Execution

Example

Chain Event Triggers

Example event object sent as the payload to your task:

Example configuration for an onchain event trigger:

Task code

Onchain Trigger Properties

Failure Handling

Cron Triggers

Example

6-field (second-granularity) example

Cron Trigger Properties

HTTP Triggers

Example

Http Trigger Properties

Base URL

HTTP Request Format

Execute HTTP trigger without parameters

Execute an HTTP trigger with parameters

Response Format

Next Steps

Using Packages

Debugging

​Local Task Execution

​Trigger Task locally with CLI

​Task Code

​Task To Task Execution

​Example

​Chain Event Triggers

​Example event object sent as the payload to your task:

​Example configuration for an onchain event trigger:

​Task code

​Onchain Trigger Properties

​Failure Handling

​Cron Triggers

​Example

​6-field (second-granularity) example

​Cron Trigger Properties

​HTTP Triggers

​Example

​Http Trigger Properties

​Base URL

​HTTP Request Format

​Execute HTTP trigger without parameters

​Execute an HTTP trigger with parameters

​Response Format

​Next Steps

Using Packages

Debugging

Local Task Execution

Trigger Task locally with CLI

Task Code

Task To Task Execution

Example

Chain Event Triggers

Example event object sent as the payload to your task:

Example configuration for an onchain event trigger:

Task code

Onchain Trigger Properties

Failure Handling

Cron Triggers

Example

6-field (second-granularity) example

Cron Trigger Properties

HTTP Triggers

Example

Http Trigger Properties

Base URL

HTTP Request Format

Execute HTTP trigger without parameters

Execute an HTTP trigger with parameters

Response Format

Next Steps