LuaTrigger

Overview

LuaTrigger (created with defineTrigger) wakes your agent when an external service posts to a trigger URL. Unlike a webhook, a trigger has no execute function — the agent turn itself does the work. Your only customisation surface is three optional, declarative slots that run server-side before the agent is invoked:

verify — authenticate the request (e.g. an HMAC signature check). Return false and the request is rejected with HTTP 401; the agent never runs.
filter — decide whether this event matters. Return false and the sender gets HTTP 200, but no agent invocation happens.
transform — shape what the agent receives. Return a message string (or a full invocation input) instead of the raw payload.

import { defineTrigger } from 'lua-cli';
import { z } from 'zod';

export default defineTrigger({
  name: 'order-created',
  description: 'Fires when the shop reports a new order',
  inputSchema: z.object({
    type: z.string(),
    data: z.object({ orderId: z.string(), total: z.number() }),
  }),
  filter: (ctx) => ctx.body.type === 'order.created',
  transform: (ctx) => `New order ${ctx.body.data.orderId} for ${ctx.body.data.total}. Confirm it and notify the customer.`,
});

After lua push, every event that passes verify and filter starts an agent turn with the transformed message. There is no handler code to maintain — the agent’s persona, skills, and tools take it from there.

A trigger needs at least one of verify, filter, or transform — a trigger with none of the three is just a paste-anywhere URL trigger, which you can create without any code via lua triggers create.

Triggers vs Webhooks vs Jobs

	LuaTrigger	LuaWebhook	LuaJob
Purpose	Wake the agent on an external event	Full request/response control	Scheduled or queued work
Handler code	None — declarative slots only	Your `execute` function	Your `execute` function
Who does the work	The agent (persona, skills, tools)	Your code	Your code
HTTP response	Framework-owned (200/401/…)	Whatever `execute` returns	n/a
Best for	”When X happens, have the agent deal with it”	Custom responses, side effects, syncing data	Cron schedules, background processing

Reach for LuaWebhook when the caller needs a specific response body or you want to run code without involving the agent. Reach for LuaTrigger when the right reaction to an event is an agent turn — triage this PR, answer this ticket, follow up on this order. See LuaWebhook and LuaJob.

Use Cases

Git Events

“A PR was assigned to me — triage it” with signature verification

Payment Events

Wake the agent on a successful Stripe payment, ignore the rest

Alerting

Point a monitoring tool at the trigger URL; the agent investigates

Automation Glue

Any service that can POST JSON can start an agent turn

Defining a Trigger

Three authoring shapes are recognised — pick whichever fits your codebase:

import { defineTrigger } from 'lua-cli';

export default defineTrigger({
  name: 'order-created',
  description: 'Fires when the shop reports a new order',
  filter: (ctx) => ctx.body.type === 'order.created',
});

import { LuaTrigger } from 'lua-cli';

export default new LuaTrigger({
  name: 'order-created',
  description: 'Fires when the shop reports a new order',
  filter: (ctx) => ctx.body.type === 'order.created',
});

import { LuaTrigger, TriggerContext } from 'lua-cli';

export default class OrderCreatedTrigger extends LuaTrigger {
  name = 'order-created';
  description = 'Fires when the shop reports a new order';

  filter(ctx: TriggerContext) {
    return ctx.body.type === 'order.created';
  }
}

Configuration Parameters

Required Fields

string

required

Unique trigger name, used as the server-side identifier.Format: URL-safe — a lowercase letter followed by lowercase letters, digits, and hyphens (e.g. 'order-created', 'github-pr-assigned'). Other names compile with a warning.

string

required

Short description shown in trigger listings. It is a note for you — it is not sent to the agent.

Slots (at least one required)

function

Authentication gate. Return false (or a promise of false) to reject the request with HTTP 401 and skip the agent entirely. Put HMAC signature checks here.Signature: (ctx: TriggerContext) => boolean | Promise<boolean>

function

Relevance gate, run after verify. Return false to acknowledge the event with HTTP 200 but skip the agent — the way to intentionally ignore events you don’t care about, without making the sender think delivery failed.Signature: (ctx: TriggerContext) => boolean | Promise<boolean>

function

Shapes the agent input, run after filter. Return either:

a string — becomes the agent’s message for the turn, or
a full invocation input object ({ messages | prompt, userId?, threadId?, systemPrompt?, ... }) — you own the whole turn.

Returning null/undefined is an error (the delivery fails with HTTP 500) — use filter to skip events, not transform.Signature: (ctx: TriggerContext) => string | AgentInvocationInput | Promise<string | AgentInvocationInput>Omit transform to use the default payload-forwarding format described in Default Agent Message.

Optional Fields

'webhook'

default:"'webhook'"

Event source. Only 'webhook' (an HTTP POST to the trigger URL) is currently supported.

ZodType

Optional Zod schema describing the event body. To type ctx.body in your slots, also pass the payload type as the generic: defineTrigger<MyEvent>({ ... }).

TriggerContext

Every slot receives the same context object:

interface TriggerContext<T = any> {
  body: T;                       // Parsed request body (type it via defineTrigger<T>)
  rawBody?: string;              // Exact unparsed request bytes (utf8)
  headers: Record<string, any>;  // Request headers — keys are lowercased
  query: Record<string, any>;    // Parsed query-string parameters
  triggerName: string;           // This trigger's name
  source: string;                // Event source ('webhook')
}

Compute HMAC signatures over ctx.rawBody, never over JSON.stringify(ctx.body). Providers like GitHub (x-hub-signature-256: sha256=…), Stripe, and Slack sign the exact bytes they send. Re-stringifying the parsed body does not reproduce those bytes (key order, whitespace, and unicode escapes all differ), so a signature computed from ctx.body will fail even for genuine requests. rawBody exists precisely for this.

Header keys arrive lowercased — read ctx.headers['x-hub-signature-256'], not ctx.headers['X-Hub-Signature-256'].

Slot Semantics

Slots run server-side, in order, on every delivery. Their outcome decides the HTTP response the sender sees:

Outcome	HTTP response	Agent invoked?	Logged status
All slots pass	`200`	✅ Yes (in the background)	`accepted` → `completed`
`verify` returns `false`	`401`	❌ No	`rejected_unverified`
`filter` returns `false`	`200`	❌ No	`skipped_filtered`
Any slot throws	`500`	❌ No	`failed`
`transform` returns `null`/`undefined`	`500`	❌ No	`failed`
Trigger is deactivated	`200`	❌ No	`skipped_inactive`
Unknown URL or token	`404`	❌ No	—

A few facts worth knowing:

Slots run in a sandbox with a 15-second budget. Keep them fast and computational — signature checks, field comparisons, string building. Don’t make network calls from slots; if the agent needs external data, let the agent fetch it with its tools during the turn.
verify failures return 401, not 500. Webhook providers treat a 401 as a configuration error and won’t retry-storm you the way they would on a 5xx.
filter failures return 200. The sender sees a successful delivery, so it won’t retry an event you deliberately ignored.
Node’s built-in crypto module is available in slots (for createHmac, timingSafeEqual), and env('KEY') reads your agent’s environment variables — the sanctioned way to get secrets into a verify check.
The agent turn is fire-and-forget. Once the slots pass, the sender gets its 200 immediately; the agent runs in the background and the outcome lands in the execution log.

Default Agent Message

When you omit transform, the agent receives the event in a standard format. With an instruction set (via lua triggers create --instruction "..."):

[Trigger: <name>] <instruction>

Payload:
<JSON-stringified body>

Without an instruction, the JSON payload directly follows the prefix — there is no Payload: label:

[Trigger: <name>] <JSON-stringified body>

The [Trigger: <name>] prefix is always present, so the agent (and any follow-up turns) can tell what started the conversation.
The instruction is the place to tell the agent what to do with the event.
The payload is capped at 50,000 characters; anything longer is truncated.

Providing a transform overrides all of this:

Return a string → the agent’s message becomes [Trigger: <name>] <your string>. The trigger’s instruction is not applied — your transform owns the message. This is the way to forward hand-picked fields from large payloads instead of hitting the 50k cap.
Return an invocation input object → you own the entire turn: message content, userId (to run as a specific user with conversation history), threadId, systemPrompt, and so on. The channel is always recorded as trigger.

// Full-control transform: run the turn as a specific user
transform: (ctx) => ({
  prompt: `Order ${ctx.body.orderId} was refunded. Apologise and offer a discount code.`,
  userId: ctx.body.customerId,   // conversation history is stored for this user
})

A transform-supplied userId takes precedence over the trigger’s own bound user — see Who the trigger turn runs as.

Who the trigger turn runs as

Every trigger has a bound user, and the agent turn it fires runs as that person:

A trigger you create yourself — lua push of a LuaTrigger, or lua triggers create — binds you, the developer who created it.
A trigger that arrives with an installed template binds the installer.

The binding is what makes user-scoped work inside a trigger-fired turn land on the right desk: an Inbox.push from a tool running in the turn reaches the bound user, User reads and writes act on them, and the conversation lands in their history — instead of a context-less system run. Identity precedence, highest first:

A transform-supplied userId. A transform that returns a full invocation input with userId owns the turn’s identity — the SDK author’s explicit choice always wins.
The trigger’s bound user. The default when the transform sets no userId (or there is no transform).
System. With no transform userId and no binding, the turn runs with a system identity and no ambient user.

Three things the binding never does:

It never comes from the request. The bound user is set server-side when the trigger is created or installed — nothing in the webhook payload, headers, or URL can choose or change who the turn runs as.
It doesn’t survive duplication. Duplicating an agent gives the copy’s triggers fresh URLs and no bound user — a copy must never fire as the original’s owner. Its turns run with system identity until the binding is re-established (re-create the trigger, or re-install the template on the copy).
It doesn’t outlive the user. If the bound user’s account is offboarded, the binding is cleared and the trigger falls back to system identity rather than acting for someone who left.

Trigger URLs and Token Security

Every trigger gets a URL of the form:

https://trigger.heylua.ai/trigger/{agentId}/{token}

The token is the secret — anyone who has the full URL can fire the trigger (subject to your verify slot). Treat the URL like a credential.
Unknown agent, unknown token, or a mismatched pair all return the same 404 — the URL shape leaks nothing about which part was wrong.
If a URL leaks, rotate it: lua triggers rotate-token --trigger <name>. The old URL stops working immediately and the CLI prints the new one.

A trigger without a verify slot accepts any request that has the URL. That is fine for low-stakes automation glue, but for anything that causes real side effects, add a verify slot with a proper signature check — don’t rely on URL secrecy alone.

Agents know their own URL

When an agent is installed from a template, the platform writes each webhook trigger’s per-install URL into the agent’s environment as LUA_TRIGGER_URL__<TRIGGER_KEY> — the trigger key upper-snaked, so github-pr-assigned becomes LUA_TRIGGER_URL__GITHUB_PR_ASSIGNED. The variable is readable with env() from tools and from trigger slots, is rewritten if the trigger’s token is rotated, and is removed when the template is uninstalled. This is what makes zero-input webhook setup possible: instead of the installer copying a URL into a provider’s settings screen, a setup tool in the template reads its own URL and registers it with the provider itself.

import { LuaTool, env } from 'lua-cli';
import { z } from 'zod';

export class SetupWebhookTool implements LuaTool {
  name = 'setup_webhook';
  description = 'Register this agent\'s trigger URL with the provider.';
  inputSchema = z.object({});

  async execute() {
    // Read at call time — the platform rewrites this on token rotation.
    const triggerUrl = env('LUA_TRIGGER_URL__ORDER_CREATED')?.trim();
    if (!triggerUrl) {
      return { ok: false, message: 'No injected trigger URL — was this agent installed from a template?' };
    }
    return registerProviderWebhook(triggerUrl); // your provider API call
  }
}

The LUA_TRIGGER_URL__ prefix is reserved: a template’s env contract cannot declare keys under it (publishing rejects them), and a hand-set variable of the same name is overwritten with the platform’s URL at install. The full pattern — pairing the injected URL with a post-install setup turn — is in Publishing Templates.

Complete Example: GitHub Pull Request Trigger

A production-shaped trigger: HMAC signature verification over the raw bytes, a filter that only lets through PRs assigned to a configured user, and a compact transform (a raw GitHub PR payload is enormous and mostly noise for the agent).

import { defineTrigger, env } from 'lua-cli';
import { createHmac, timingSafeEqual } from 'crypto';

interface GitHubPullRequestEvent {
  action?: string;
  assignee?: { login?: string };
  pull_request?: {
    number?: number;
    title?: string;
    html_url?: string;
  };
  repository?: { full_name?: string };
}

/** Constant-time comparison; length mismatch short-circuits (length is not secret). */
function safeEqual(expected: string, provided: string): boolean {
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(provided, 'utf8');
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

export default defineTrigger<GitHubPullRequestEvent>({
  name: 'github-pr-assigned',
  description: 'Wakes the agent when a GitHub PR is assigned to the configured user',
  source: 'webhook',

  // GitHub signs the exact wire bytes → verify against ctx.rawBody
  verify: (ctx) => {
    const secret = env('GITHUB_WEBHOOK_SECRET');
    const signature = ctx.headers['x-hub-signature-256'];
    if (!secret || !ctx.rawBody || typeof signature !== 'string') return false;
    const expected = 'sha256=' + createHmac('sha256', secret).update(ctx.rawBody, 'utf8').digest('hex');
    return safeEqual(expected, signature);
  },

  // Only wake the agent when a PR is assigned to our user
  filter: (ctx) => {
    const body = ctx.body ?? {};
    if (body.action !== 'assigned') return false;
    const configured = (env('GITHUB_USERNAME') ?? '').trim().toLowerCase();
    return !!configured && body.assignee?.login?.toLowerCase() === configured;
  },

  // Hand-pick fields — the raw payload is huge and would just waste the
  // agent's context (and risk the ~50k default-payload cap)
  transform: (ctx) => {
    const pr = ctx.body.pull_request ?? {};
    const repo = ctx.body.repository?.full_name ?? 'unknown/unknown';
    return [
      `PR assigned on GitHub: ${repo}#${pr.number ?? '?'}`,
      `Title: ${pr.title ?? '(no title)'}`,
      `URL: ${pr.html_url ?? '(no url)'}`,
      `Review it now and post a summary of the risk areas.`,
    ].join('\n');
  },
});

Configure the trigger URL and the same secret in your repository’s webhook settings (Repository → Settings → Webhooks, content type application/json), and set GITHUB_WEBHOOK_SECRET and GITHUB_USERNAME with lua env.

Minimal Example: Filter Only

The smallest useful trigger — no verification, no transform, just a relevance gate. The agent receives the default [Trigger: …] Payload: … message.

import { defineTrigger } from 'lua-cli';

export default defineTrigger({
  name: 'deployment-finished',
  description: 'Wakes the agent when a deployment completes',
  filter: (ctx) => ctx.body?.status === 'succeeded' || ctx.body?.status === 'failed',
});

This trigger accepts any POST that has the URL — there is no verify slot. Acceptable for internal tooling behind URL secrecy; not acceptable for anything a third party could abuse. Rotate the token immediately if the URL leaks.

Using with LuaAgent

import { LuaAgent } from 'lua-cli';
import githubPrAssigned from './triggers/pr-assigned.trigger';

export const agent = new LuaAgent({
  name: 'my-agent',
  persona: '...',
  skills: [...],

  triggers: [
    githubPrAssigned,
  ],
});

On lua push, each trigger is compiled, versioned, and deployed like any other primitive, and your lua.skill.yaml gains a triggers: section tracking the deployed name, ID, and version:

triggers:
  - name: github-pr-assigned
    triggerId: 5f4c9a1e-2b7d-4c03-9e88-1a2b3c4d5e6f
    version: 1.0.1

Observability

Every delivery — invoked, filtered, rejected, or failed — is recorded as an execution. Inspect them with the CLI:

lua triggers logs --trigger github-pr-assigned
lua triggers logs --trigger github-pr-assigned --limit 5 --json

Status	Meaning
`accepted`	Slots passed; the agent turn is in flight
`completed`	The agent turn finished; the response text is stored on the execution
`failed`	A slot threw, the transform returned nothing, or the agent invocation failed
`rejected_unverified`	`verify` returned `false` (sender saw 401)
`skipped_filtered`	`filter` returned `false` (sender saw 200)
`skipped_inactive`	Trigger was deactivated at delivery time

See the Triggers Command for the full management workflow — listing, creating URL triggers, activating, rotating tokens, and deleting.

Triggers Command

Manage triggers from the CLI — list, logs, rotate-token

LuaWebhook

Full request/response control with your own execute function

LuaJob

Scheduled and queued background work

Environment Variables

env(‘KEY’) — secrets for your verify slot

Getting Started

Core Concepts

Workflows

CLI Commands

API Reference

Template & Examples

Overview

Triggers vs Webhooks vs Jobs

Use Cases

Git Events

Payment Events

Alerting

Automation Glue

Defining a Trigger

Configuration Parameters

Required Fields

Slots (at least one required)

Optional Fields

TriggerContext

Slot Semantics

Default Agent Message

Who the trigger turn runs as

Trigger URLs and Token Security

Agents know their own URL

Complete Example: GitHub Pull Request Trigger

Minimal Example: Filter Only

Using with LuaAgent

Observability

Triggers Command

LuaWebhook

LuaJob

Environment Variables

See Also

​Overview

​Triggers vs Webhooks vs Jobs

​Use Cases

Git Events

Payment Events

Alerting

Automation Glue

​Defining a Trigger

​Configuration Parameters

​Required Fields

​Slots (at least one required)

​Optional Fields

​TriggerContext

​Slot Semantics

​Default Agent Message

​Who the trigger turn runs as

​Trigger URLs and Token Security

​Agents know their own URL

​Complete Example: GitHub Pull Request Trigger

​Minimal Example: Filter Only

​Using with LuaAgent

​Observability

​Related APIs

Triggers Command

LuaWebhook

LuaJob

Environment Variables

​See Also

Overview

Triggers vs Webhooks vs Jobs

Use Cases

Defining a Trigger

Configuration Parameters

Required Fields

Slots (at least one required)

Optional Fields

TriggerContext

Slot Semantics

Default Agent Message

Who the trigger turn runs as

Trigger URLs and Token Security

Agents know their own URL

Complete Example: GitHub Pull Request Trigger

Minimal Example: Filter Only

Using with LuaAgent

Observability

Related APIs

See Also