Skip to main content
The trigger function creates a trigger object that can be referenced by a custom component. Triggers are the entry point of an integration flow — they receive an inbound request or event and pass a payload to the flow’s subsequent action steps.

​
Function signature

function trigger<
  TInputs extends Inputs,
  TConfigVars extends ConfigVarResultCollection,
  TAllowsBranching extends boolean,
  TResult extends TriggerResult<TAllowsBranching, TriggerPayload>,
>(
  definition: TriggerDefinition<TInputs, TConfigVars, TAllowsBranching, TResult>
): TriggerDefinition<TInputs, TConfigVars, TAllowsBranching, TResult>

​
Parameters

​
definition
TriggerDefinition
required
An object describing the trigger. See fields below.

​
TriggerDefinition fields

​
definition.display
ActionDisplayDefinition
required
Controls how the trigger appears in the Prismatic UI.
​
definition.perform
TriggerPerformFunction
required
The async function that runs when this trigger is invoked. Receives context, payload, and params.
perform: (
  context: ActionContext<TConfigVars>,
  payload: TriggerPayload,
  params: ActionInputParameters<TInputs>
) => Promise<TResult>
​
definition.inputs
TInputs
required
A record of input field definitions presented to the integration builder. See input.
​
definition.scheduleSupport
'invalid' | 'valid' | 'required'
required
Whether this trigger supports execution on a recurring schedule.
  • "invalid" — schedule is not supported
  • "valid" — schedule is optional
  • "required" — schedule must be configured
​
definition.synchronousResponseSupport
'invalid' | 'valid' | 'required'
required
Whether this trigger supports synchronous HTTP responses back to the caller.
  • "invalid" — synchronous response is not supported
  • "valid" — synchronous response is optional
  • "required" — synchronous response must be configured
​
definition.onInstanceDeploy
TriggerEventFunction
An async function called when an instance using this trigger is deployed. Use to register webhooks with external services.
onInstanceDeploy: (
  context: ActionContext<TConfigVars>,
  params: ActionInputParameters<TInputs>
) => Promise<void>
​
definition.onInstanceDelete
TriggerEventFunction
An async function called when an instance using this trigger is deleted. Use to deregister webhooks from external services.
​
definition.webhookLifecycleHandlers
object
Optional handlers for creating and deleting webhooks independently of instance deploy/delete lifecycle.
​
definition.terminateExecution
boolean
When true, terminates execution after the trigger runs.
​
definition.breakLoop
boolean
When true, breaks out of the enclosing loop step.
​
definition.allowsBranching
boolean
When true, this trigger supports conditional branching.
​
definition.staticBranchNames
string[]
Static branch names when allowsBranching is true.
​
definition.dynamicBranchInput
string
Key of the input field that determines branch names dynamically.
​
definition.examplePayload
Awaited<ReturnType<perform>>
Example return value from perform, used to preview output shape in the UI.

​
Return type

The perform function must return a Promise resolving to a TriggerResult:
​
payload
TriggerPayload
required
The trigger payload passed through to subsequent steps in the flow.
​
response
HttpResponse
HTTP response to send back to the caller when synchronousResponseSupport is "valid" or "required".
​
instanceState
Record<string, unknown>
Values to persist in the flow-specific instance state.
​
crossFlowState
Record<string, unknown>
Values to persist in the cross-flow state.
​
executionState
Record<string, unknown>
Values to persist for the duration of the current execution.
​
integrationState
Record<string, unknown>
Values to persist across all flows and versions of an integration instance.
​
branch
string
Required when allowsBranching is true. The name of the branch to take.
​
polledNoChanges
boolean
Set to true in a polling trigger result to indicate no new data was found.
​
failed
boolean
Set by the platform to indicate whether the trigger failed.
​
error
Record<string, unknown>
Set by the platform with error details when the trigger fails.

​
Example

import { trigger, input } from "@prismatic-io/spectral";

export const webhookTrigger = trigger({
  display: {
    label: "Webhook",
    description: "Trigger a flow when a webhook payload is received",
  },
  inputs: {
    secret: input({
      label: "Webhook Secret",
      type: "password",
      required: false,
      comments: "Optional HMAC secret to verify webhook signatures",
    }),
  },
  scheduleSupport: "invalid",
  synchronousResponseSupport: "valid",
  perform: async (context, payload, params) => {
    // Optionally verify the webhook signature
    if (params.secret) {
      const signature = payload.headers["x-signature"];
      verifySignature(payload.rawBody.data as Buffer, params.secret, signature);
    }

    return {
      payload,
      response: {
        statusCode: 200,
        contentType: "application/json",
        body: JSON.stringify({ received: true }),
      },
    };
  },
  onInstanceDeploy: async (context, params) => {
    context.logger.info("Instance deployed — registering webhook with external service");
    // Call external API to register the webhook URL
  },
  onInstanceDelete: async (context, params) => {
    context.logger.info("Instance deleted — deregistering webhook");
    // Call external API to remove the webhook registration
  },
  examplePayload: {
    payload: {
      headers: { "content-type": "application/json" },
      body: { data: { event: "order.created", orderId: "ord_123" } },
      rawBody: { data: Buffer.from("{}") },
      queryParameters: {},
      pathFragment: "",
      webhookUrls: {},
      webhookApiKeys: {},
      invokeUrl: "https://hooks.prismatic.io/trigger/example",
      executionId: "exec_abc",
      customer: { id: "cust_1", name: "Acme Corp", externalId: "acme" },
      instance: { id: "inst_1", name: "My Integration" },
      user: { id: "", name: "", email: "", externalId: "" },
      integration: { id: "int_1", name: "Order Sync", versionSequenceId: "1" },
      flow: { id: "flow_1", name: "Main Flow" },
      startedAt: "2026-01-01T00:00:00Z",
      globalDebug: false,
    },
  },
});

function verifySignature(body: Buffer, secret: string, signature: string) {
  // HMAC verification logic
}