Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.colossal.sh/llms.txt

Use this file to discover all available pages before exploring further.

Colossal app triggers run in one of three modes. A trigger is just a routing key — a string identifier that workflows subscribe to. The invocation mode (async, sync side-effect, sync return) is set by the platform code that fires the trigger, not by the trigger string itself. The categories below describe how the platform invokes each trigger and what guarantees the workflow has.

​
Async triggers

Most events trigger agents asynchronously. The event is dispatched to a message queue, the originating operation completes immediately, and matching agents run in the background. Async events include:
  • ORDER_CREATED, ORDER_CONFIRMED, ORDER_COMPLETED
  • CUSTOMER_CREATED, CUSTOMER_UPDATED
  • CHECKOUT_STARTED, CHECKOUT_ADDRESS_SET, CHECKOUT_PAYMENT_SELECTED, CHECKOUT_COMPLETED, CHECKOUT_PAYMENT_FAILED
  • PAYMENT_SUCCEEDED, PAYMENT_FAILED
  • INVOICE_CREATED, INVOICE_PAID
  • All product, variant, price, and media events
Use async agents for side effects that don’t need to block the user: sending emails, syncing to a CRM, notifying a Slack channel.

​
Sync side-effect triggers

Cart mutation events trigger agents synchronously to modify state. The mutation waits for matching agents to complete before returning a response to the caller. This lets agents modify the cart in the middle of a user action. Sync side-effect events:
  • CART_ITEM_ADDED
  • CART_ITEM_UPDATED
  • CART_ITEM_REMOVED

​
Cart modifications

When a cart mutation triggers a sync agent, the agent runs before the response is returned to the customer. This enables use cases like:
  • Applying automatic discounts when an item is added
  • Validating inventory before allowing an item to be added
  • Adding complementary products automatically
Sync side-effect agents add latency to the cart operation. Keep them fast. Avoid HTTP calls to slow external services or complex multi-step logic.If a sync side-effect agent fails, the cart mutation still succeeds. The error is logged server-side but not returned to the customer. These agents cannot reject cart operations. They can only modify the cart before the response is sent.

​
Sync return triggers

Some triggers are synchronous request/response — the platform calls the workflow and waits for typed data back. The workflow’s result is consumed by the platform to make a decision (e.g., apply a discount, validate a code, calculate shipping). Sync return events:
  • CHECKOUT_VALIDATE_DISCOUNT_CODE — the customer entered a discount code; the workflow looks it up and returns whether it’s valid plus the discount amount.

​
Constraints

Sync return workflows are subject to additional rules enforced at save time:
  • Must end in a transform step that produces the trigger’s required output type
  • Cannot use delay, wait_for_event, parallel, map, or ai_reasoning steps (these would stall the user-facing operation)
  • Only one enabled workflow per sync return trigger per workspace
  • Execution timeout: 10 seconds

​
Output contracts

Each sync return trigger has a required output type exposed via get_workflow_schema. The transform step’s output_schema and mapping must produce this shape. The platform validates the result with Pydantic at runtime — invalid results are rejected. For example, CHECKOUT_VALIDATE_DISCOUNT_CODE must return a DiscountValidationResult: 
{
  "valid": true,
  "code": "SAVE20",
  "discount_type": "fixed_amount",
  "amount_minor": 500,
  "label": "$5 off",
  "max_uses": 100
}
Sync return workflows run on the user’s critical path. Keep them fast and deterministic. Use convention-based column names in your data sources, or call query_integration_data once at workflow creation time to discover the schema and bake the mapping into the transform step.If a sync return workflow fails or returns an invalid result, the user action is rejected with a generic error message.