CableKnit AI Docs

Trigger Types

Every automation has a trigger_type that defines what starts a new run. When the trigger fires, CableKnit creates an AutomationRun and populates case_context.trigger_data with the trigger payload.

inbound_email

Triggers when an email is received at the automation’s inbound address. CableKnit parses the email and passes the content as the trigger payload.

{
  "trigger_type": "inbound_email",
  "trigger_config": {}
}

No configuration required. When a company installs your plugin, CableKnit assigns a unique inbound email address for this automation. Any email sent to that address starts a new run.

Trigger payload

{
  "from": "vendor@example.com",
  "to": "intake-abc123@in.cableknit.ai",
  "subject": "Invoice #1234 - Follow Up",
  "body": "Hi, we wanted to follow up on invoice #1234...",
  "html_body": "<p>Hi, we wanted to follow up...</p>",
  "attachments": []
}

Access in your workflow: ,, etc.

Always mark `trigger_data.body` as an `untrusted_key` in `ai_assess` actions. Email bodies come from external senders and may contain content designed to manipulate LLM behavior.

schedule

Triggers on a cron schedule. Useful for recurring reports, daily reviews, and periodic compliance checks.

{
  "trigger_type": "schedule",
  "trigger_config": {
    "cron": "0 9 * * 1",
    "timezone": "America/Chicago"
  }
}
Config field Type Required Description
cron string Yes Standard 5-part cron expression
timezone string No IANA timezone name. Defaults to UTC.

Common cron patterns

Schedule Expression
Every Monday at 9am 0 9 * * 1
Weekdays at 8am 0 8 * * 1-5
First of every month at 6am 0 6 1 * *
Every day at midnight 0 0 * * *
Every hour 0 * * * *

Trigger payload

Scheduled runs receive a minimal payload:

{
  "triggered_at": "2026-03-10T09:00:00Z",
  "trigger_type": "schedule"
}

webhook

Triggers when an external system sends an HTTP POST to the automation’s unique webhook URL. CableKnit generates a unique URL and token for each webhook automation when a company installs your plugin.

{
  "trigger_type": "webhook",
  "trigger_config": {}
}

When installed, the automation gets a dedicated URL in the format:

https://app.cableknit.ai/webhooks/automation/<token>

The URL and token are available in the API response (webhook_url, webhook_token) and in the automation detail view. Any POST to this URL with a JSON body starts a new run.

HMAC verification

For added security, you can require external systems to sign their payloads. Set a webhook_secret in trigger_config:

{
  "trigger_type": "webhook",
  "trigger_config": {
    "webhook_secret": "your-shared-secret"
  }
}

When a secret is set, CableKnit requires an X-Webhook-Signature header containing the HMAC-SHA256 hex digest of the raw request body, signed with the secret. Requests without a valid signature are rejected with 401 Unauthorized.

Rate limiting

Inbound webhook endpoints are rate-limited to 60 requests per minute per automation. Requests exceeding the limit receive a 429 Too Many Requests response.

Payload security

All incoming webhook payloads are scanned for prompt injection patterns before a run is created. Payloads that match known injection patterns are rejected with 422 Unprocessable Entity.

Always mark webhook `trigger_data` as an `untrusted_key` in `ai_assess` actions. Webhook payloads come from external systems and may contain content designed to manipulate LLM behavior.

Response codes

Code Meaning
200 Run created. Response includes run_id and status: "accepted".
401 HMAC signature missing or invalid (only when webhook_secret is configured)
404 Unknown webhook token
410 Automation is not active (paused or disabled)
422 Payload flagged for injection
429 Rate limit exceeded

Trigger payload

The full JSON body of the POST request is available as trigger_data, with an added source field:

{
  "trigger_data": {
    "source": "webhook",
    "record_id": "abc123",
    "status": "submitted",
    "submitted_by": "jane@example.com"
  }
}

event

Triggers when a connected service emits a specific event. Requires a connector to be configured.

{
  "trigger_type": "event",
  "trigger_config": {
    "event_type": "ConnectorEvent",
    "channel": "envelopes",
    "conditions": [
      { "field": "payload.status", "operator": "eq", "value": "completed" }
    ]
  }
}
Config field Type Required Description
event_type string Yes The type of connector event to listen for
channel string No The event channel (varies by connector)
conditions array No Filter conditions — only trigger if these match the event payload

See Connectors for the full list of event channels, trigger examples, and how to declare connector requirements in plugin.json.