API reference for createTrigger() — defines webhook or polling triggers with lifecycle hooks for enabling, disabling, and processing events.

Create a Trigger

createTrigger() defines an event source that starts a pipeline execution. Triggers can be webhook-based (push) or polling-based (pull).

Signature

import { createTrigger } from "@triggo/connector-sdk";

function createTrigger<TAuth = unknown, TProps = unknown>(
  config: TriggerConfig<TAuth, TProps>,
): TriggerDefinition<TAuth, TProps>;

TriggerConfig

Field	Type	Required	Description
`name`	`string`	Yes	Unique trigger identifier. Must be snake_case (e.g., `new_message`).
`displayName`	`string`	Yes	Human-readable name shown in the UI.
`description`	`string`	Yes	What event this trigger listens for.
`props`	`Record<string, PropertyDefinition>`	Yes	Input properties. Pass `{}` for no inputs.
`type`	`TriggerType`	Yes	Either `TRIGGER_TYPES.WEBHOOK` or `TRIGGER_TYPES.POLLING`.
`onEnable`	`(context: TriggerContext) => Promise<void \| OnEnableResult>`	Yes	Called when the pipeline is activated. Register webhooks or start polling here.
`onDisable`	`(context: TriggerContext) => Promise<void>`	Yes	Called when the pipeline is deactivated. Clean up webhooks or stop polling.
`run`	`(context: TriggerContext) => Promise<unknown[]>`	Yes	Processes an incoming event. Must return an array of event objects.
`outputSchema`	`Record<string, unknown>`	No	JSON Schema describing the trigger output shape. Used by the AI system.
`sampleData`	`unknown`	No	Example output data for UI previews and testing.
`test`	`(context: TriggerContext) => Promise<unknown[]>`	No	Returns sample events for the test panel without requiring a real event.
`aiHints`	`string`	No	Additional context for the AI pipeline generator.

Trigger Types

import { TRIGGER_TYPES } from "@triggo/connector-sdk";

TRIGGER_TYPES.WEBHOOK  // "WEBHOOK" — external service pushes events via HTTP
TRIGGER_TYPES.POLLING  // "POLLING" — Triggo periodically checks for new events

Webhook Triggers

Webhook triggers receive events pushed by external services. Triggo generates a unique webhook URL for each active pipeline. The context.webhookUrl field contains this URL during onEnable.

Polling Triggers

Polling triggers are invoked on a schedule. Use context.store to track the last poll timestamp or cursor, then fetch only new events.

Lifecycle

Pipeline Activated → onEnable(context) → (register webhook / store cursor)
                                              ↓
Event Received   → run(context)        → returns event[]
                                              ↓
Pipeline Stopped → onDisable(context)  → (unregister webhook / cleanup)

OnEnableResult

onEnable can optionally return an object with an external webhook ID for tracking:

interface OnEnableResult {
  readonly externalWebhookId?: string;
}

TriggerContext

interface TriggerContext<TAuth = unknown, TProps = unknown> {
  readonly auth: TAuth;
  readonly propsValue: TProps;
  readonly store: StoreContext;
  readonly webhookUrl?: string;
  readonly payload?: unknown;
}

Field	Type	Description
`auth`	`TAuth`	Authenticated credentials.
`propsValue`	`TProps`	Resolved property values.
`store`	`StoreContext`	Persistent key-value store.
`webhookUrl`	`string \| undefined`	The generated webhook URL. Available in `onEnable` for webhook triggers.
`payload`	`unknown \| undefined`	The raw incoming event payload. Available in `run` for webhook triggers.

Validation Rules

Name format -- must match /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/ (non-empty snake_case)
Invalid names throw an Error at creation time

Webhook Trigger Example

import {
  createTrigger,
  TRIGGER_TYPES,
  ConnectorError,
} from "@triggo/connector-sdk";
import { CONNECTOR_ERROR_CODES } from "@triggo/shared";

export const newOrder = createTrigger({
  name: "new_order",
  displayName: "New Order",
  description: "Triggers when a new order is created in the shop.",
  props: {},
  type: TRIGGER_TYPES.WEBHOOK,
  outputSchema: {
    type: "object",
    properties: {
      orderId: { type: "string" },
      amount: { type: "number" },
      currency: { type: "string" },
    },
    required: ["orderId", "amount", "currency"],
  },
  sampleData: { orderId: "ORD-001", amount: 4999, currency: "RUB" },

  async onEnable(context) {
    const auth = context.auth as { secret: string };
    const response = await fetch("https://api.shop.com/webhooks", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${auth.secret}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        url: context.webhookUrl,
        events: ["order.created"],
      }),
    });

    if (!response.ok) {
      throw new ConnectorError(
        CONNECTOR_ERROR_CODES.UPSTREAM_ERROR,
        "Failed to register webhook",
      );
    }

    const { id } = (await response.json()) as { id: string };
    await context.store.put("webhookId", id);
    return { externalWebhookId: id };
  },

  async onDisable(context) {
    const webhookId = (await context.store.get("webhookId")) as string | null;
    if (webhookId) {
      const auth = context.auth as { secret: string };
      await fetch(`https://api.shop.com/webhooks/${webhookId}`, {
        method: "DELETE",
        headers: { Authorization: `Bearer ${auth.secret}` },
      });
      await context.store.delete("webhookId");
    }
  },

  async run(context) {
    const payload = context.payload as Record<string, unknown>;
    return [
      {
        orderId: payload["id"],
        amount: payload["amount"],
        currency: payload["currency"],
      },
    ];
  },
});

Polling Trigger Example

import { createTrigger, TRIGGER_TYPES } from "@triggo/connector-sdk";

export const newItem = createTrigger({
  name: "new_item",
  displayName: "New Item",
  description: "Polls for new items every interval.",
  props: {},
  type: TRIGGER_TYPES.POLLING,

  async onEnable(context) {
    await context.store.put("lastPollTime", new Date().toISOString());
  },

  async onDisable(context) {
    await context.store.delete("lastPollTime");
  },

  async run(context) {
    const auth = context.auth as { secret: string };
    const since = ((await context.store.get("lastPollTime")) as string) ?? new Date(0).toISOString();

    const response = await fetch(
      `https://api.example.com/items?since=${since}`,
      { headers: { Authorization: `Bearer ${auth.secret}` } },
    );
    const items = (await response.json()) as unknown[];

    await context.store.put("lastPollTime", new Date().toISOString());
    return items;
  },
});

Create a Trigger

On this page