Workflow triggers

A trigger is the entry point of every workflow, defining which event starts execution. Nothing runs until a trigger fires.

Every workflow has exactly one trigger, tied to a real event in DevRev: an object is created, an object is updated, a timer fires, or a manual invocation. Triggers produce output data, the full object that caused the event, which is available to all downstream steps via the variable selector. For "updated" triggers, the output includes both the current object and an old object (the pre-update snapshot), allowing you to compare what changed.

Filter conditions are strongly recommended on all triggers. Without them, the workflow runs on every matching event (for example, every ticket created in the entire workspace). Filters narrow when the workflow fires and are considered best practice for performance and precision.

Trigger reference

Object creation triggers

These fire the moment a new object is added. They have no input configuration (no fields to watch), they simply fire on every creation event matching the filter conditions.

Ticket Created (ticket_created)

Fires when a new ticket is created. This is one of the most commonly used triggers - the entry point for auto-routing, auto-assignment, acknowledgment messages, and SLA timers.

Issue Created (issue_created)

Fires when a new issue is created.

Conversation Created (conversation_created)

Fires when a new customer conversation begins, whether via Plug, email, Slack, or WhatsApp.

Account Created (account_created)

Fires when a new account is added. Useful for onboarding sequences and welcome communications.

Contact Created (contact_created)

Fires when a new contact (customer) is created.

Object update triggers

These fire when specified fields change on an existing object. You must configure which fields to watch.

Ticket Updated (ticket_updated)

Output: All fields from Ticket Created, plus:

Issue Updated (issue_updated)

Fields to watch: applies_to_part, artifacts, body, developed_with, owned_by, priority, reported_by, sprint, stage, subtype, tags, target_close_date, target_start_date, title

Output: All fields from Issue Created, plus old_issue (pre-update snapshot), modified_by, modified_date.

Conversation Updated (conversation_updated)

Fields to watch: stage, tags, owned_by, group, is_frozen, sentiment

Output: All fields from Conversation Created, plus old_conversation (pre-update snapshot).

Account Updated (account_updated)

Fields to watch: description, display_name, domains, external_refs, owned_by, tags, tier

Output: All fields from Account Created, plus old_account, tags, tier (enum: tier_1, tier_2, tier_3).

Contact Updated (contact_updated)

Fields to watch: description, display_name, email, phone_numbers, external_refs, tags

Output: All fields from Contact Created, plus old_rev_user, rev_org.

Object link triggers

These fire when a link between two DevRev objects is created or removed. Use them to react to a relationship rather than to a field change, for example to comment on a ticket when it is linked to an issue.

Link triggers exist for the linkable pairs listed under Link operations in the Complete action library section of the Workflow node reference article. Custom objects that participate in linked relationships also emit link and unlink events (the Custom objects in workflows section of the Workflow node reference article).

Link direction matters. A link trigger fires for the object that is the source of the link, which is not always the object you expect.

SLA tracker triggers

These fire on the SLA metric attached to a ticket or conversation, so a workflow can act when a target is approaching or has been missed rather than polling for it.

Only replies from human users complete an SLA first-response target. Comments posted by bots or system accounts do not.

Timer trigger

Timer Trigger (timer_trigger)

Fires on a schedule. Supports two modes:

Manual trigger

Manual Trigger (manual_trigger)

Fires when explicitly invoked by a user. Has no static input schema - the output schema is configured at design time by the workflow author using dynamic schema.

API trigger

API Triggers let you programmatically start a DevRev workflow from an external service or from another workflow. This enables you to connect any system that can make HTTP requests: CI/CD pipelines, monitoring tools, CRMs, custom applications directly into your DevRev automation, or to reuse a common series of steps across multiple workflows by calling one workflow from another.

API Triggers at a glance

An API Trigger is a trigger node that starts a workflow when it receives an authenticated HTTP POST request. You define the input parameters the workflow expects (name, type, required/optional), and when an API call is made with matching data, the workflow executes with those values available as variables in every downstream node.

Step 1: Add an API Trigger to Your Workflow

How to add the trigger

1. Create a new workflow or open an existing one. You'll land on a blank canvas with "Add a first step.." Alternatively Click "+ Step" in the bottom toolbar, and select "Trigger".

2. In the Select Trigger dialog, search for "API Trigger" node

   The trigger node is added to your canvas.

Step 2: Define Input Parameters

Input parameters define what data your workflow expects when triggered. Each parameter becomes a variable that downstream nodes can reference.

Configure the trigger node

Click the API Trigger node to open its configuration panel. You'll see:

• Attributes:

  • Input Parameters* (required) — "The input parameters of the trigger." This is where you define the variables that must be passed when calling the trigger.

  • Filter — "Filter for the trigger event." Optional conditions that must be met for the workflow to execute.

Add input parameters

1. Click on the Input Parameters field. The variable selector panel opens on the right.

2. Click + Add field to create a new parameter.

3. In the Field creator, configure:

4. Click Save. The parameter appears in the Input Parameters field showing its name, type, and required status (e.g., test1 · Text · Required).

You can add multiple parameters by repeating this process. Each parameter you define here must be supplied (if marked required) in the API call's payload for the workflow to trigger successfully.

Add filters (optional)

Filters let you conditionally run the workflow only when the incoming parameter values meet certain criteria. If filter conditions are not met, the workflow run is skipped and the caller receives a response indicating the trigger conditions were not satisfied.

Step 3: Trigger the Workflow

There are two ways to trigger an API Trigger workflow:

Option A: Test from the UI (▶ Button)

You can test your API Trigger directly from the workflow canvas without making an external API call.

1. Hover over the API Trigger node on the canvas. A play button (▶) appears on the right side of the node.

2. Click the play button. A "Trigger workflow" modal opens with the subtitle "Provide the input values to trigger this workflow run."

3. The modal shows one input field per parameter you defined. Required fields are marked with a red asterisk (*). Each field shows placeholder text like Add {parameter_name}.

4. Fill in the values and click Run workflow. The workflow executes immediately with the provided data.

Use this to quickly validate your workflow logic before connecting external systems.

Option B: Trigger via API (External Systems)

For production use, trigger the workflow by making an HTTP POST request.

Endpoint:

POST https://api.devrev.ai/internal/workflows.trigger

Headers:

Authentication: Use a DevRev Personal Access Token (PAT). If calling from an external service, generate a PAT from Settings > Personal Access Tokens in DevRev and include it in the Authorization header.

Authorization Type: Basic

Request body — single trigger workflow:

When your workflow has a single API Trigger, the payload is straightforward:

{
  "id": "workflow-XXXX",
  "payload": {
    "value": {
      "Name": "John",
      "Phone_number": 29,
      "Ticket_id": "TKT-1000"
    }
  }
}

Request body for multiple triggers in one workflow:

When your workflow has multiple API Trigger nodes (e.g., API Trigger, API Trigger 2, API Trigger 3), you must include a step_reference_key to specify which trigger to fire. The key corresponds to the trigger's label on the canvas, you can click the "ellipsis" on the trigger node and copy the "step reference key"

{
  "id": "workflow-XXXX",
  "step_reference_key": "api_trigger_2",
  "payload": {
    "value": {
      "test3": 2
    }
  }
}

Fetching step reference key for API Trigger

Click on the "API Trigger" node and you will find a "⋮" on the top right. Click on "Copy step reference key" as shown in the image

Option C: Trigger from Another Workflow (HTTP Node)

To chain workflows — for example, to reuse a common sequence of steps — use DevRev's HTTP action node to call the API Trigger endpoint from within a separate workflow.

Configure the HTTP node as follows:

The Body field accepts a JSON code editor where you build the request payload:

{
  "id": "workflow-4530",
  "payload": {
    "value": {
      "test3": 2
    }
  }
}

When triggering from within a workflow, use an active connection (configured in the Auth Token field) instead of a raw PAT token. This keeps credentials managed centrally and avoids hardcoding tokens.

Use Input Parameters in Downstream Nodes

Once the API Trigger fires, the input parameter values are available as variables throughout the entire workflow. Reference them in any downstream node using the Insert variable button.

1. Open any node downstream of the API Trigger.

2. Click Insert variable on the field where you want to use a trigger parameter.

3. Navigate to API Trigger / Output and select the parameter you need.

Input parameters can be used in:

• Ask AI / AI Agent Skill nodes — as part of the prompt context

• HTTP nodes — as dynamic values in URLs, headers, or request bodies

• Code nodes — as variables in custom logic

• If Else / Router nodes — to branch workflow logic based on input values

• Set Variable nodes — to store or transform trigger values for later use

Type matching requirement

The parameter type you defined in the API Trigger must match the type expected by the downstream field. If you defined test3 as Int, you can only insert it into fields that accept a number type.

When to use an API Trigger

Customer feedback processing

An external web form submits customer feedback to DevRev via API Trigger. The workflow routes the feedback to the appropriate team, creates a ticket, and sends a confirmation email — all triggered by a single POST request from the form backend.

Cross-workflow orchestration

A primary workflow handles ticket creation. When certain conditions are met, an HTTP node triggers a secondary workflow (via API Trigger) that runs a specialized set of steps — like an AI-powered analysis or a multi-step approval chain. This lets you build reusable workflow modules instead of duplicating logic.

Issue escalation from monitoring

Monitoring tools like Datadog or PagerDuty call the API Trigger endpoint when critical thresholds are breached. The workflow creates a high-priority tikcet/incident, pages the on-call engineer, and starts an escalation timer.

Tips and Best Practices

• Match parameter names exactly. The keys in your payload.value must match the parameter names defined in the API Trigger node. Mismatched keys result in missing values at runtime. Names are case-sensitive.

• Use the ▶ button first. Always test your workflow from the canvas using the play button before connecting external systems. This validates both your input schema and downstream logic without needing to set up API calls.

• Use connections for internal triggers. When triggering from another workflow via the HTTP node, use an active connection (Auth Token) rather than hardcoding a PAT. This keeps credentials managed centrally.

• Use a PAT for external triggers. When calling from external services, use a DevRev Personal Access Token in the Authorization header. Store it in environment variables or a secrets manager — never hardcode it in your application.

• Include step_reference_key for multi-trigger workflows. If your workflow has more than one API Trigger node, every API call must include the step_reference_key field to specify which trigger to fire. The value is the trigger's label (e.g., api_trigger_2) and is case-sensitive.

• Publish before triggering. The workflow must be published before it can be triggered via API. Note the workflow ID (workflow-XXXX) from the URL after publishing.

• Use filters to guard execution. Add filter conditions on the trigger node to prevent unnecessary workflow runs when parameter values don't meet your criteria.

• Handle errors in external callers. Implement retry logic for transient network failures. Validate your payload structure before sending requests and monitor HTTP response codes.

Troubleshooting

Node Reference

API Trigger

AI Agent Skill trigger

AI Agent Skill Trigger (agent_skill_trigger)

Fires when an AI agent invokes the workflow as a skill. This is the trigger that turns a workflow into something an agent can call: the agent decides, from the conversation, that the skill is needed and passes the input parameters the workflow declares.

Because the agent supplies the parameters, the trigger has no fixed output schema. You define the contract at design time, the same way you do on an API Trigger.

Configuration:

1. Add an AI Agent Skill Trigger step to the workflow.

2. Under Input Parameters, add each field the agent will supply. Use the field creator to set a name and a field type.

3. (Optional) Add filter conditions under Filter to narrow which trigger events start a run.

4. Publish the workflow, then register it as a skill on the agent.

Supported field types for input parameters:

Every parameter you define is available to downstream steps through the variable selector as an output of the trigger step.

Runs started by an agent skill appear in the Runs tab like any other run, and can be filtered by the conversation that triggered them or by the user who triggered them.

Configuring filter conditions

Filter conditions narrow when a trigger fires. They prevent a workflow from running on every event of the given type, by deciding at the source whether an event is relevant, before any workflow logic runs.

For example: if a workflow is set to run when an issue’s stage changes, without filters it fires on every stage update. With a trigger filter, you can specify that the workflow should run only when the stage moves to "Completed", skipping all other updates entirely.

Why trigger filters matter:

• Simpler workflow design — removes the need for "if/else" checks inside the workflow. Structures stay cleaner and easier to maintain.

• Cleaner runs list — only meaningful executions appear, making it easier to monitor real activity and measure workflow success.

• Better performance — prevents unnecessary executions, reducing latency when many events fire simultaneously.

• Targeted execution — workflows trigger only when specific field changes or conditions occur, giving predictable behavior.

• Stability at scale — reduces system noise and loop risks under high-volume scenarios.

Filters are optional but highly recommended. Use them to filter at the source rather than after the trigger.

How filters work:

• When configuring a trigger, click "Add filter condition" in the trigger's configuration panel.

• Select the field to filter on (from the trigger's output schema - e.g., priority, applies_to_part, stage).

• Select an operator (e.g., equals, not equals, contains, is empty). Available operators depend on the field type and are loaded dynamically from the backend.

• Enter the comparison value (a literal value or a reference).

• Combine multiple conditions using AND (all must be true) or OR (any must be true).

Notes:

• Text comparisons are case-sensitive unless you enable the Case Insensitive toggle on the condition. Enable it rather than listing every case variation of a value.

• The more precise your trigger filter, the fewer unnecessary workflow runs you generate.

• For "updated" triggers, the fields_to_watch configuration acts as the first filter - the workflow only fires when one of the watched fields changes.