Utilities

General-purpose operations an automation can run as App Action steps. Unlike commerce primitives’ actions, these aren’t tied to a Colossal object.

Email

send_email

Sends an email to a recipient.Input

string

required

string

required

minLen: 1, maxLen: 998.

string

Default: "".

string

Default: "".

string | null

Output

string

Notifications

post_notification

Send a notification about this automation. It reaches whoever the automation belongs to - the person who created it, whoever set that run going, plus anyone added to an agent that uses it. A builder who has never touched it is not notified, and there is no way to name a recipient. The default channel when the merchant asks to be notified without naming one.Input

string

required

Short headline shown in the notification row.

string

required

A sentence or two of detail below the title.

string

One of: info, suggestion, warning, action_required, celebration. Default: "info".

string | null

Optional dedupe key; matching non-deleted rows are returned instead of creating a new one.

Output

string | null

HTTP request

http_request

Sends an HTTP request to any URL.Input

string

required

minLen: 1, maxLen: 2083.

enum (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`)

required

object

integer

min: 1, max: 300. Default: 30.

Output

integer

min: 0.

object | string | null

object

Security

The http_request action supports custom headers, so you can include a secret key to verify that incoming requests are from Colossal. When configuring a webhook request in your automation, 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

⌘I

Get started

Platform

Agents

Automations

Storefront

Dev Tools

Email

Notifications

HTTP request

Security

Best practices

​Email

​Notifications

​HTTP request

​Security

​Best practices

Email

Notifications

HTTP request

Security

Best practices