Task Triggers - Compose

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.
`parallel_processing`	boolean	No	Process events concurrently through an internal durable queue instead of one at a time. Defaults to `false`. See Parallel processing.
`max_concurrency`	integer	No	How many events are processed at the same time. Must be a positive integer; defaults to `10`. Only used when `parallel_processing` is `true`.
`confirmations`	integer	No	Hold each event until its block is this many blocks deep before running the task. Must be a non-negative integer; defaults to `0` (run immediately). Requires `parallel_processing: true`. See Confirmations.

Parallel processing

By default, onchain events are delivered one at a time: Goldsky sends an event, waits for your task to finish, then sends the next one. If a task takes 30 seconds and 2,000 events land in a burst, the last event runs hours late. Set parallel_processing: true to switch the trigger to queued, concurrent delivery. Events are written to an internal durable queue as they are indexed, and a worker in your app runs up to max_concurrency of them at the same time.

name: "my-app"
api_version: "stable"
tasks:
  - name: "on_transfer"
    path: "./tasks/on_transfer.ts"
    triggers:
      - type: "onchain_event"
        network: "ethereum"
        contract: "0xb74de3F91e04d0920ff26Ac28956272E8d67404D"
        events:
          - "Transfer(address,address,uint256)"
        parallel_processing: true
        max_concurrency: 50

Your task code does not change. main(context, payload) still receives a single event, and each event still gets its own run ID, its own context function cache, and the same crash recovery as a serially delivered event. What to know before enabling it:

Ordering is not preserved. Events run concurrently, so a later event can finish before an earlier one. Only enable this if each event can be handled independently. Keep the default (serial) delivery if your task depends on events arriving in block order.
Concurrency is app-wide. One queue worker drains the queue for the whole app, so the first max_concurrency it finds on an onchain trigger sets the limit for every parallel trigger in that app. Set the same value on each trigger to avoid confusion.
Backpressure is handled for you. If the queue fills up, Compose rejects further deliveries with a 429 and Goldsky retries them with backoff, so events are not lost — they arrive later.
Reorgs cancel queued events. If an event is retracted (a reorg) while it is still sitting in the queue, the queued entry is removed and the task never runs for it. Events that have already started running are unaffected.
Operators can retune concurrency live. Goldsky can override max_concurrency on a running app via the COMPOSE_TRIGGER_CONCURRENCY environment variable, without a redeploy. Reach out in support if you need this while tuning.

Confirmations

Onchain triggers fire as soon as the event is indexed at the chain head, which means a reorg can retract an event your task already acted on. If the task moved real money — a settlement, a payout, a compliance gate — that is unrecoverable. Set confirmations: N to hold each event in the queue until its block is N blocks deep. Compose polls the chain head and releases the event once event block + N <= current block.

name: "my-app"
api_version: "stable"
tasks:
  - name: "settle_trade"
    path: "./tasks/settle_trade.ts"
    triggers:
      - type: "onchain_event"
        network: "ethereum"
        contract: "0xb74de3F91e04d0920ff26Ac28956272E8d67404D"
        parallel_processing: true
        confirmations: 10

confirmations requires parallel_processing: true — the confirmation buffer is part of the queue. Setting it without parallel processing fails validation.
confirmations: 0 (the default) fires immediately, exactly as before.
While an event waits, it is held in the queue. If a reorg retracts it before it is released, the event is cancelled and your task never runs for it.
Choose the depth from your own risk tolerance: deeper is safer but adds latency roughly equal to N block times. Removing confirmations from your manifest releases anything still waiting on the next deploy.

This is the inbound counterpart to the outbound confirmation and reorg options on writeContract — see Reorg handling for transactions your task sends.

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. With parallel_processing: true the same retry rules apply per event, but a failing event never stalls the others: each event is claimed from the queue independently, and one exhausting its retries doesn’t hold back the rest.

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

Compose task triggers: cron, HTTP, and onchain

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

Parallel processing

Confirmations

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

​Parallel processing

​Confirmations

​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

Parallel processing

Confirmations

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