Triggers

Colossal app event triggers. Full list of events and their payload schemas.

The Colossal app emits events when things happen in your project: orders placed, items added to cart, payments processed. These events trigger agents and are available through the HTTP request action for forwarding to external systems.

Each event follows a consistent envelope format:

{
  "signal_type": "ORDER_CREATED",
  "org_id": 1,
  "project_id": 42,
  "entity_id": "123",
  "entity_type": "order",
  "payload": { ... },
  "correlation_id": "abc-123",
  "source": "user",
  "timestamp": "2025-01-01T12:00:00Z"
}

Field	Type	Description
signal_type	string	The event type identifier
org_id	integer	Organization ID
project_id	integer	Project ID
entity_id	string	Primary entity identifier
entity_type	string	Type of entity (e.g. "order", "cart", "product")
payload	object	Event-specific payload (see below)
correlation_id	string | null	Optional trace/correlation ID
source	string	One of "user", "workflow", or "system"
timestamp	string	ISO 8601 UTC timestamp

Common Types

These types are reused across multiple event payloads.

Customer

Field	Type	Description
uid	string	Unique customer identifier
email	string	Customer email address
first_name	string	First name
last_name	string	Last name

LineItem

Field	Type	Description
uid	string	Unique line item identifier
name	string	Product name
sku	string	Product SKU
price	number	Unit price
quantity	integer	Quantity ordered
category	string	Product category

CartItemData

Field	Type	Description
product_uid	string	Product identifier
product_name	string	Product name
quantity	integer	Quantity in cart
unit_price	number	Price per unit
line_total	number	Total for this line

Address

Field	Type	Description
line1	string	Street address
line2	string?	Apartment, suite, etc.
city	string	City
state	string?	State or province
postal_code	string	Postal/ZIP code
country	string	Country code

Order events

ORDER_CREATED — Cart converted into an order during checkout, before payment.

Field	Type	Description
order_uid	string	Unique order identifier
total_price	number	Order total
total_amount	number	Order total
customer	Customer	Customer details
line_items	LineItem[]	Items in the order

ORDER_CONFIRMED — Payment processed successfully, before fulfillment.

Field	Type	Description
order_uid	string	Unique order identifier
total_price	number	Order total before tax
total_amount	number	Order total including tax
subtotal_amount	number	Subtotal before tax
tax	number	Tax amount
customer	Customer	Customer details
line_items	LineItem[]	Items in the order
has_subscription	boolean	Whether order contains a subscription

ORDER_COMPLETED — Order fully complete. Payment processed and fulfillment finished.

Field	Type	Description
order_uid	string	Unique order identifier
total_price	number	Order total before tax
total_amount	number	Order total including tax
subtotal_amount	number	Subtotal before tax
tax	number	Tax amount
customer	Customer	Customer details
line_items	LineItem[]	Items in the order
has_subscription	boolean	Whether order contains a subscription
fulfillment_method	string	Fulfillment method (e.g., digital)

Customer events

CUSTOMER_CREATED — New customer account created.

Field	Type	Description
customer_uid	string	Unique customer identifier
email	string	Customer email address
full_name	string	Customer full name

CUSTOMER_UPDATED — Customer details updated.

Field	Type	Description
customer_uid	string	Unique customer identifier
email	string	Customer email address
full_name	string	Customer full name
changed_fields	string[]	List of fields that changed

Cart events

CART_CREATED — New shopping cart initialized.

Field	Type	Description
cart_uid	string	Unique cart identifier

CART_ITEM_ADDED — Item added to a cart.

Field	Type	Description
cart_uid	string	Unique cart identifier
item	CartItemData	Added item details
cart_item_count	integer	Total items in cart
cart_subtotal	number	Cart subtotal

CART_ITEM_UPDATED — Cart item quantity changed.

Field	Type	Description
cart_uid	string	Unique cart identifier
item	CartItemData	Updated item details
previous_quantity	integer	Previous quantity
cart_item_count	integer	Total items in cart
cart_subtotal	number	Cart subtotal

CART_ITEM_REMOVED — Item removed from a cart.

Field	Type	Description
cart_uid	string	Unique cart identifier
removed_item	CartItemData	Removed item details
cart_item_count	integer	Total items in cart
cart_subtotal	number	Cart subtotal

Checkout events

CHECKOUT_STARTED — Checkout session initiated.

Field	Type	Description
checkout_uid	string	Unique checkout session identifier
cart_uid	string?	Cart identifier (if from cart)
order_uid	string?	Order identifier
total_amount	number	Checkout total
item_count	integer	Number of items
customer_email	string?	Customer email

CHECKOUT_ADDRESS_SET — Billing address provided during checkout.

Field	Type	Description
checkout_uid	string	Unique checkout session identifier
order_uid	string?	Order identifier
total_amount	number	Checkout total
customer_email	string?	Customer email
billing_address	Address	Billing address

CHECKOUT_PAYMENT_SELECTED — Payment provider selected during checkout.

Field	Type	Description
checkout_uid	string	Unique checkout session identifier
order_uid	string?	Order identifier
total_amount	number	Checkout total
customer_email	string?	Customer email
payment_provider	string	Selected payment provider
previous_provider	string?	Previously selected provider

CHECKOUT_COMPLETED — Checkout completed successfully.

Field	Type	Description
checkout_uid	string	Unique checkout session identifier
order_uid	string?	Order identifier
total_amount	number	Checkout total
customer_email	string?	Customer email
payment_provider	string?	Payment provider used

CHECKOUT_PAYMENT_FAILED — Payment failed during checkout.

Field	Type	Description
checkout_uid	string	Unique checkout session identifier
order_uid	string?	Order identifier
total_amount	number	Checkout total
customer_email	string?	Customer email
payment_provider	string?	Payment provider used
error_code	string?	Error code
error_message	string?	Error message

CHECKOUT_VALIDATE_DISCOUNT_CODE — Customer submitted a discount code at checkout. Synchronous return trigger — workflow must produce a DiscountValidationResult. See trigger modes.

Field	Type	Description
checkout_uid	string	Unique checkout session identifier
order_uid	string?	Order identifier
discount_code	string	The code the customer entered
subtotal_amount	number	Order subtotal in dollars (used to compute percentage discounts)
currency	string	Currency code
customer_email	string?	Customer email (for per-customer limits)

Required workflow output:

Field	Type	Description
valid	boolean	Whether the code is accepted
code	string	Echo of the submitted code
discount_type	"fixed_amount" | "percentage"	How the discount is calculated
amount_minor	integer?	Discount in cents (required when discount_type=fixed_amount)
percentage_off	integer?	Whole-number percent off (required when discount_type=percentage, 0-100)
label	string?	Human-readable label shown at checkout
max_uses	integer?	Cap on total redemptions (null = unlimited)

Invoice events

INVOICE_CREATED — New invoice created.

Field	Type	Description
invoice_uid	string	Unique invoice identifier
invoice_number	string?	Human-readable invoice number
customer_uid	string?	Customer identifier
order_uid	string?	Associated order identifier
currency	string	Currency code (e.g., USD)
subtotal	integer	Subtotal in cents
tax	integer	Tax in cents
total	integer	Total in cents
status	string	Invoice status
source	string	Invoice source (e.g., order)

INVOICE_PAID — Invoice paid.

Field	Type	Description
invoice_uid	string	Unique invoice identifier
invoice_number	string?	Human-readable invoice number
customer_uid	string?	Customer identifier
order_uid	string?	Associated order identifier
currency	string	Currency code
total	integer	Total paid in cents

Payment events

PAYMENT_SUCCEEDED — Payment completed successfully.

Field	Type	Description
payment_uid	string	Unique payment identifier
invoice_uid	string	Associated invoice identifier
amount	integer	Amount in cents
currency	string	Currency code
payment_provider	string	Payment provider (e.g., stripe)
payment_method	string?	Payment method (e.g., card)
card_brand	string?	Card brand (e.g., visa)
card_last4	string?	Last 4 digits of card
transaction_id	string?	Provider transaction ID

PAYMENT_FAILED — Payment failed.

Field	Type	Description
payment_uid	string	Unique payment identifier
invoice_uid	string	Associated invoice identifier
amount	integer	Amount in cents
currency	string	Currency code
payment_provider	string	Payment provider
payment_method	string?	Payment method
failure_code	string?	Failure code
failure_message	string?	Failure message
decline_code	string?	Decline code from provider

Product events

PRODUCT_CREATED — New product created.

Field	Type	Description
uid	string	Unique product identifier
name	string	Product name
handle	string	URL-friendly handle
description	string?	Product description
variant_properties	object?	Variant property definitions

PRODUCT_UPDATED — Product details modified.

Field	Type	Description
uid	string	Unique product identifier
name	string	Product name
handle	string	URL-friendly handle
description	string?	Product description
variant_properties	object?	Variant property definitions
is_archived	boolean	Whether product is archived
changed_fields	string[]	List of fields that changed

PRODUCT_PUBLISHED — Product made visible in the storefront.

Field	Type	Description
uid	string	Unique product identifier
name	string	Product name

PRODUCT_DRAFT_DISCARDED — Product draft discarded.

Field	Type	Description
uid	string	Unique product identifier

PRODUCT_ARCHIVED — Product archived.

Field	Type	Description
uid	string	Unique product identifier

PRODUCT_UNARCHIVED — Product restored from archive.

Field	Type	Description
uid	string	Unique product identifier

Product variant events

PRODUCT_VARIANT_CREATED — New variant added to a product.

Field	Type	Description
uid	string	Unique variant identifier
product_uid	string	Parent product identifier
name	string?	Variant name
properties	object?	Variant properties (e.g., {"tier": "pro"})
inventory_count	integer?	Inventory count

PRODUCT_VARIANT_UPDATED — Variant details changed.

Field	Type	Description
uid	string	Unique variant identifier
product_uid	string	Parent product identifier
name	string?	Variant name
properties	object?	Variant properties
inventory_count	integer?	Inventory count
is_archived	boolean	Whether variant is archived
changed_fields	string[]	List of fields that changed

PRODUCT_VARIANT_DELETED — Variant removed from a product.

Field	Type	Description
uid	string	Unique variant identifier
product_uid	string	Parent product identifier

Product price events

PRODUCT_PRICE_CREATED — Price tier added to a variant.

Field	Type	Description
uid	string	Unique price identifier
variant_uid	string	Parent variant identifier
name	string?	Price name (e.g., Monthly)
price	object	Price details ({amount, type})
currency	string	Currency code
recurring_interval	string?	Billing interval (e.g., month)
trial_duration	string?	Trial period (e.g., 14d)
is_default	boolean	Whether this is the default price

PRODUCT_PRICE_UPDATED — Price tier changed.

Field	Type	Description
uid	string	Unique price identifier
variant_uid	string	Parent variant identifier
name	string?	Price name
price	object	Price details
currency	string	Currency code
recurring_interval	string?	Billing interval
trial_duration	string?	Trial period
is_default	boolean	Whether this is the default price
changed_fields	string[]	List of fields that changed

PRODUCT_PRICE_DELETED — Price tier removed.

Field	Type	Description
uid	string	Unique price identifier
variant_uid	string	Parent variant identifier

Product media events

PRODUCT_MEDIA_ADDED — Media files attached to a variant.

Field	Type	Description
variant_uid	string	Variant identifier
media_uids	string[]	List of added media identifiers

PRODUCT_MEDIA_REMOVED — Media files removed from a variant.

Field	Type	Description
variant_uid	string	Variant identifier
media_uids	string[]	List of removed media identifiers

Product deliverable events

PRODUCT_DELIVERABLE_CREATED — New deliverable created.

Field	Type	Description
uid	string	Unique deliverable identifier
type	string	Deliverable type (e.g., digital_download)
name	string	Deliverable name
config	object?	Type-specific configuration

PRODUCT_DELIVERABLE_UPDATED — Deliverable details changed.

Field	Type	Description
uid	string	Unique deliverable identifier
type	string	Deliverable type
name	string	Deliverable name
config	object?	Type-specific configuration
changed_fields	string[]	List of fields that changed

PRODUCT_DELIVERABLE_ARCHIVED — Deliverable archived.

Field	Type	Description
uid	string	Unique deliverable identifier

Product variant deliverable events

PRODUCT_VARIANT_DELIVERABLE_ADDED — Deliverable attached to a variant.

Field	Type	Description
variant_uid	string	Variant identifier
deliverable_uid	string	Deliverable identifier

PRODUCT_VARIANT_DELIVERABLE_REMOVED — Deliverable removed from a variant.

Field	Type	Description
variant_uid	string	Variant identifier
deliverable_uid	string	Deliverable identifier

Event Summary

Event	Entity Type	Description
ORDER_CREATED	order	Cart converted to order
ORDER_CONFIRMED	order	Payment processed
ORDER_COMPLETED	order	Payment and fulfillment done
CUSTOMER_CREATED	customer	New customer account
CUSTOMER_UPDATED	customer	Customer details changed
CART_CREATED	cart	New cart initialized
CART_ITEM_ADDED	cart	Item added to cart
CART_ITEM_UPDATED	cart	Cart item quantity changed
CART_ITEM_REMOVED	cart	Item removed from cart
CHECKOUT_STARTED	checkout	Checkout session initiated
CHECKOUT_ADDRESS_SET	checkout	Billing address provided
CHECKOUT_PAYMENT_SELECTED	checkout	Payment provider selected
CHECKOUT_COMPLETED	checkout	Checkout completed
CHECKOUT_PAYMENT_FAILED	checkout	Payment failed
CHECKOUT_VALIDATE_DISCOUNT_CODE	checkout	Sync return — discount code submitted, workflow returns validation
INVOICE_CREATED	invoice	Invoice created
INVOICE_PAID	invoice	Invoice paid
PAYMENT_SUCCEEDED	payment	Payment completed
PAYMENT_FAILED	payment	Payment failed
PRODUCT_CREATED	product	New product created
PRODUCT_UPDATED	product	Product details changed
PRODUCT_PUBLISHED	product	Product visible in store
PRODUCT_DRAFT_DISCARDED	product	Product draft discarded
PRODUCT_ARCHIVED	product	Product archived
PRODUCT_UNARCHIVED	product	Product restored
PRODUCT_VARIANT_CREATED	product_variant	Variant added
PRODUCT_VARIANT_UPDATED	product_variant	Variant changed
PRODUCT_VARIANT_DELETED	product_variant	Variant removed
PRODUCT_PRICE_CREATED	product_price	Price tier added
PRODUCT_PRICE_UPDATED	product_price	Price tier changed
PRODUCT_PRICE_DELETED	product_price	Price tier removed
PRODUCT_MEDIA_ADDED	product_media	Media attached
PRODUCT_MEDIA_REMOVED	product_media	Media removed
PRODUCT_DELIVERABLE_CREATED	product_deliverable	Deliverable created
PRODUCT_DELIVERABLE_UPDATED	product_deliverable	Deliverable changed
PRODUCT_DELIVERABLE_ARCHIVED	product_deliverable	Deliverable archived
PRODUCT_VARIANT_DELIVERABLE_ADDED	product_variant_deliverable	Deliverable attached to variant
PRODUCT_VARIANT_DELIVERABLE_REMOVED	product_variant_deliverable	Deliverable removed from variant

Webhook Security

Agent webhook actions support custom headers, so you can include a secret key to verify that incoming requests are from Colossal. When configuring a webhook action in your agent, add an authorization header with a secret value:

{
  "headers": {
    "X-Webhook-Secret": "your-secret-key"
  }
}

Then verify it on your server:

app.post('/webhooks/colossal', (req, res) => {
  const secret = req.headers['x-webhook-secret'];

  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  // Process webhook
  res.status(200).send('OK');
});

Best Practices

1. Use a secret header - Add a shared secret to your webhook headers to verify requests
2. Handle duplicate events - Use correlation_id for idempotency
3. Return 200 quickly - Process events asynchronously
4. Handle retries - We retry failed webhooks up to 3 times
5. Monitor webhook endpoints - Ensure high availability