API triggers

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.

Configuring 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.

Adding 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.

Adding 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.

Using 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