Skip to main content

Trigger Nodes

Trigger nodes are entry points for automations. They fire when an external event occurs (webhook) or when a periodic check finds new data (polling).

Trigger modes​

ModeDescriptionUse case
webhookExternal service sends HTTP POST to a generated URLShopify orders, GitHub events, Stripe payments
pollingWorker periodically calls your handler to check for eventsRSS feeds, API endpoints without webhooks
bothSupport both webhook and pollingServices that offer webhooks but need a fallback

Create a project​

lumio init my-trigger

When prompted:

  • Category: automation_node
  • Node type: Trigger
  • Trigger mode: Choose webhook, polling, or both

Handler​

Trigger handlers use defineAutomationTrigger with onWebhook and/or onPoll methods:

import { defineAutomationTrigger } from "@zaflun/lumio-sdk/server";

defineAutomationTrigger({
  onWebhook: async (ctx) => {
    const payload = ctx.webhookBody;
    if (payload.event !== "order.created") {
      return { fired: false };
    }
    return {
      fired: true,
      output: {
        order_id: payload.id,
        customer_name: payload.customer.name,
        total: payload.total_price,
        currency: payload.currency,
      },
    };
  },
  onPoll: async (ctx) => {
    const lastCheck = await ctx.cache.get("last_check_ts");
    const res = await ctx.fetch(
      `https://api.example.com/events?since=${lastCheck}`
    );
    const events = await res.json();

    if (events.length === 0) return null;

    await ctx.cache.set("last_check_ts", Date.now().toString());
    return {
      fired: true,
      output: events[0],
    };
  },
});

Return value​

Both onWebhook and onPoll return a TriggerResult (or null):

FieldTypeRequiredDescription
firedbooleanYesWhether the trigger should start the automation
outputRecord<string, unknown>Only when fired: trueEvent data. Must match the output_schema from the manifest.

Returning null or { fired: false } silently ignores the event. No automation runs.

Webhook flow​

When a user enables an automation with your trigger:

  1. Lumio generates a unique webhook URL and a 64-character hex secret
  2. The user configures the external service with this URL and secret
  3. External service sends POST /v1/automation/webhooks/{extension_id}/{install_id} with X-Webhook-Secret header
  4. The API validates the secret and forwards to the Automation Worker
  5. Your onWebhook handler runs in V8
  6. If fired: true, the automation engine runs the full flow

The webhook URL is displayed in the Automation Builder when the user selects a webhook trigger node.

Polling flow​

For polling triggers, the Automation Worker runs your onPoll handler at the configured interval:

  1. User enables the automation
  2. The Worker starts a poll loop at poll_interval_seconds (10-300, default 30)
  3. Each iteration calls your onPoll handler
  4. If fired: true, the automation engine runs the full flow
  5. On disable, the poll loop stops

Use ctx.cache to track the last-checked timestamp and avoid re-processing events.

Manifest configuration​

{
  "node_type": "trigger",
  "node": {
    "trigger_mode": "webhook",
    "poll_interval_seconds": null,
    "input_schema": {
      "type": "object",
      "properties": {
        "shop_domain": { "type": "string", "title": "Shop Domain" }
      },
      "required": ["shop_domain"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "customer_name": { "type": "string" },
        "total": { "type": "number" },
        "currency": { "type": "string" }
      }
    }
  }
}

For polling triggers, set poll_interval_seconds to a value between 10 and 300.

Next steps​