Colossal - Colossal

The Colossal app emits events when things happen in your project: orders placed, products published, payments processed. These events trigger agents and are available through the HTTP request action for forwarding to external systems. Cart and checkout events live in Storefront triggers. Each event follows a consistent envelope format:

event

object

Show properties

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", "product", "invoice")

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

object

Show properties

uid

string

Unique customer identifier

string

Customer email address

first_name

string

First name

last_name

string

Last name

LineItem

object

Show properties

uid

string

Unique line item identifier

name

string

Product name

sku

string

Product SKU

price

number

Unit price

quantity

integer

Quantity ordered

`ORDER_CREATED`

Cart converted into an order during checkout, before payment.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

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)

`ORDER_CANCELLED`

Order cancelled.

payload

object

Show properties

order_uid

string

Unique order identifier

cancelled_at

string

ISO 8601 timestamp of cancellation

total_amount

number

Order total

currency

string

Currency code

customer

Customer

Customer details

payment_provider

string

Payment provider

refund_reason

string

Reason, if provided

`ORDER_REFUNDED`

Order refunded.

payload

object

Show properties

order_uid

string

Unique order identifier

refunded_at

string

ISO 8601 timestamp of refund

total_amount

number

Order total refunded

currency

string

Currency code

customer

Customer

Customer details

payment_provider

string

Payment provider

refund_reason

string

Reason, if provided

Customer events

`CUSTOMER_CREATED`

New customer account created.

payload

object

Show properties

customer_uid

string

Unique customer identifier

string

Customer email address

full_name

string

Customer full name

`CUSTOMER_UPDATED`

Customer details updated.

payload

object

Show properties

customer_uid

string

Unique customer identifier

string

Customer email address

full_name

string

Customer full name

changed_fields

string[]

List of fields that changed

Invoice events

`INVOICE_CREATED`

New invoice created.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

uid

string

Unique product identifier

name

string

Product name

`PRODUCT_DRAFT_DISCARDED`

Product draft discarded.

payload

object

Show properties

uid

string

Unique product identifier

`PRODUCT_ARCHIVED`

Product archived.

payload

object

Show properties

uid

string

Unique product identifier

`PRODUCT_UNARCHIVED`

Product restored from archive.

payload

object

Show properties

uid

string

Unique product identifier

Product variant events

`PRODUCT_VARIANT_CREATED`

New variant added to a product.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

uid

string

Unique variant identifier

product_uid

string

Parent product identifier

Product price events

`PRODUCT_PRICE_CREATED`

Price tier added to a variant.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

uid

string

Unique price identifier

variant_uid

string

Parent variant identifier

Product media events

`PRODUCT_MEDIA_ADDED`

Media files attached to a variant.

payload

object

Show properties

variant_uid

string

Variant identifier

media_uids

string[]

List of added media identifiers

`PRODUCT_MEDIA_REMOVED`

Media files removed from a variant.

payload

object

Show properties

variant_uid

string

Variant identifier

media_uids

string[]

List of removed media identifiers

Product deliverable events

`PRODUCT_DELIVERABLE_CREATED`

New deliverable created.

payload

object

Show properties

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.

payload

object

Show properties

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.

payload

object

Show properties

uid

string

Unique deliverable identifier

Product variant deliverable events

`PRODUCT_VARIANT_DELIVERABLE_ADDED`

Deliverable attached to a variant.

payload

object

Show properties

variant_uid

string

Variant identifier

deliverable_uid

string

Deliverable identifier

`PRODUCT_VARIANT_DELIVERABLE_REMOVED`

Deliverable removed from a variant.

payload

object

Show properties

variant_uid

string

Variant identifier

deliverable_uid

string

Deliverable identifier

Notification events

`NOTIFICATION_POSTED`

A notification is posted to the workspace inbox. Filter with choice steps on notification_type, category, or severity; per-type fields live under notification_payload.

payload

object

Show properties

notification_uid

string

Unique notification identifier

notification_type

string

Notification type

severity

string

Severity level

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

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

​Common Types

​ORDER_CREATED

​ORDER_CONFIRMED

​ORDER_COMPLETED

​ORDER_CANCELLED

​ORDER_REFUNDED

​CUSTOMER_CREATED

​CUSTOMER_UPDATED

​INVOICE_CREATED

​INVOICE_PAID

​PAYMENT_SUCCEEDED

​PAYMENT_FAILED

​PRODUCT_CREATED

​PRODUCT_UPDATED

​PRODUCT_PUBLISHED

​PRODUCT_DRAFT_DISCARDED

​PRODUCT_ARCHIVED

​PRODUCT_UNARCHIVED

​PRODUCT_VARIANT_CREATED

​PRODUCT_VARIANT_UPDATED

​PRODUCT_VARIANT_DELETED

​PRODUCT_PRICE_CREATED

​PRODUCT_PRICE_UPDATED

​PRODUCT_PRICE_DELETED

​PRODUCT_MEDIA_ADDED

​PRODUCT_MEDIA_REMOVED

​PRODUCT_DELIVERABLE_CREATED

​PRODUCT_DELIVERABLE_UPDATED

​PRODUCT_DELIVERABLE_ARCHIVED

​PRODUCT_VARIANT_DELIVERABLE_ADDED

​PRODUCT_VARIANT_DELIVERABLE_REMOVED

​NOTIFICATION_POSTED

​Webhook Security

​Best Practices

Common Types

`ORDER_CREATED`

`ORDER_CONFIRMED`

`ORDER_COMPLETED`

`ORDER_CANCELLED`

`ORDER_REFUNDED`

`CUSTOMER_CREATED`

`CUSTOMER_UPDATED`

`INVOICE_CREATED`

`INVOICE_PAID`

`PAYMENT_SUCCEEDED`

`PAYMENT_FAILED`

`PRODUCT_CREATED`

`PRODUCT_UPDATED`

`PRODUCT_PUBLISHED`

`PRODUCT_DRAFT_DISCARDED`

`PRODUCT_ARCHIVED`

`PRODUCT_UNARCHIVED`

`PRODUCT_VARIANT_CREATED`

`PRODUCT_VARIANT_UPDATED`

`PRODUCT_VARIANT_DELETED`

`PRODUCT_PRICE_CREATED`

`PRODUCT_PRICE_UPDATED`

`PRODUCT_PRICE_DELETED`

`PRODUCT_MEDIA_ADDED`

`PRODUCT_MEDIA_REMOVED`

`PRODUCT_DELIVERABLE_CREATED`

`PRODUCT_DELIVERABLE_UPDATED`

`PRODUCT_DELIVERABLE_ARCHIVED`

`PRODUCT_VARIANT_DELIVERABLE_ADDED`

`PRODUCT_VARIANT_DELIVERABLE_REMOVED`

`NOTIFICATION_POSTED`

Webhook Security

Best Practices