Triggers

A trigger starts a session with no person present. Use a trigger to automate recurring or event-driven work.

Trigger types

Kortix supports two trigger types. There is no third type.

• cron — runs on a schedule you set.
• webhook — runs when an external service sends a signed request to the project's webhook URL.

You define triggers in the project manifest, kortix.yaml. Each trigger holds a prompt that renders as the fired session's first message. Runtime state — such as the last fire time and status — lives outside the manifest, in the database. Firing a trigger does not create a commit.

Creating, updating, or deleting a trigger through the API, SDK, or dashboard writes directly to the default branch. It does not go through a change request (CR). Editing kortix.yaml inside a session and running kortix ship follows the normal branch and CR flow instead.

Set up a cron trigger

kortix triggers add daily-digest --type cron \
  --cron "0 0 9 * * 1-5" --timezone America/Los_Angeles \
  --prompt "Summarize yesterday's activity and save it as a daily note."

kortix ship

kortix triggers ls

Set up a webhook trigger

A webhook trigger needs a secret. Kortix uses it to check the signature on every incoming request.

kortix secrets set WEBHOOK_SECRET=<a-random-value>

kortix triggers add new-lead --type webhook \
  --secret-env WEBHOOK_SECRET \
  --prompt "A new lead arrived: {{ body.name }} ({{ body.email }}). Add it to the CRM."

kortix ship

POST /v1/webhooks/projects/<project-id>/<slug>

By default, each fire starts a fresh session on a new branch. A trigger can instead reuse or pin a session, and a webhook trigger can filter which payloads start one — see Session strategy and Payload templating below.

Config shape

# kortix.yaml
triggers:
  - slug: daily-digest # required, lowercase + dashes, unique per project
    name: Daily digest # optional, defaults to slug
    type: cron # "cron" | "webhook", required
    agent: kortix # optional, defaults to "default"
    model: anthropic/claude-sonnet-4-5 # optional, resolves at fire time if unset
    enabled: true # optional, default true
    cron: "0 0 9 * * 1-5" # 6-field expression, mutually exclusive with run_at
    timezone: America/Los_Angeles # IANA name, default UTC
    session_mode: reuse # "fresh" | "reuse" | "pinned" | "keyed", default "fresh"
    filter: # optional, webhook payload guard
      "body.data.direction": "inbound"
    prompt: "Summarize {{ body.text }}" # required, template string

Legacy kortix.toml uses the same fields in a different container; see legacy TOML.

Fields

A cron trigger needs cron or run_at, never both. A webhook trigger without secret_env is rejected — there is no unauthenticated webhook.

Session strategy

session_mode controls which session a fire re-prompts. Kortix tries the modes below in order and falls through on failure at each step.

1. pinned — re-prompt the exact session_id. If that session is gone or failed, fall through.
2. keyed — render session_key against the payload, then look up the most recent non-failed session previously stamped with that exact key. If the key renders empty, or no session matches, fall through to a fresh session. It never falls through to another key's session.
3. reuse — re-prompt the most recent non-failed session this trigger previously created. A pinned trigger falls back here too, before falling further.
4. fresh — create a new sandbox and branch. This is the default, and the final fallback for every mode. The new session becomes the trigger's session for future reuse and keyed fires.

Every trigger-fired session is created with project visibility (any project member can see it), not private to whoever configured or fired the trigger.

Payload templating

prompt and session_key render with the same engine: {{ token.dotted.path }}. A missing value renders as an empty string — no error, no leftover {{ }}. Objects and arrays render as JSON. session_key is trimmed and truncated to 512 characters.

Every fire also gets {{ trigger.slug }}, {{ trigger.type }}, and {{ trigger.kind }} (always git). The rest of the variable set depends on how the trigger fired.

{{ message.text }} is hardcoded to an empty string on a manual fire, and {{ message.source }} to manual_test. A manual fire is not a way to inject test input into the prompt.

filter compares dotted paths as strings against the same payload the prompt sees. It exists to break loops. For example, a source that reports both sides of a conversation would otherwise re-fire the agent on its own reply.

Webhook signature

Fires on POST /v1/webhooks/projects/{projectId}/{slug}. Kortix checks the request in this order, with a constant-time comparison:

1. HMAC signature — header X-Kortix-Signature: sha256=<hmac> (the sha256= prefix is optional) or the GitHub-compatible X-Hub-Signature-256. HMAC-SHA256 over the raw request body, using the secret named by secret_env.
2. Static token, only when no signature header is present, for senders that cannot HMAC-sign a body. Send the secret as X-Kortix-Token: <secret>, Authorization: Bearer <secret>, or Authorization: Basic <base64(user:secret)> (the password half is the token).

Endpoints

Pause and resume

A project-level switch stops every trigger in the project at once, independent of each trigger's own enabled field. While paused, the scheduler skips the project and inbound webhooks return 200 with { status: "skipped" } — no session fires. A manual fire still works. Use this when the same repository runs on two control planes (for example, dev and production) so cron does not fire twice. CLI: kortix triggers pause and kortix triggers resume. See CLI for the full kortix triggers command group.

Limits and reliability

• The scheduler polls every 60 seconds. Cron precision is best-effort to the minute, even though the expression has a seconds field.
• Each project allows 3 triggered sessions provisioning at once, by default. The account's plan-tier active-session cap can also apply. A fire past either limit returns queued (202) instead of failing, and runs once a slot frees up.
• A manual or webhook fire has a 45-second timeout. Loading the manifest has a 30-second timeout.
• A cron fire is keyed on the due schedule slot, so a fire that timed out but actually landed does not duplicate on retry. A webhook fire is keyed on the delivery ID header, or a hash of the body and signature when the sender sends no ID.