Journey Triggers

Every journey starts with a trigger. You choose the type when you create the journey, and it determines how people enter the workflow.

Trigger	How it works	Data contract	Best for
API Invoke	Your code sends a POST request to invoke a specific journey	You define a typed schema; Courier uses it for editor autofill and variable hints	App-triggered flows where you control the payload (signups, purchases, actions)
Webhook	Courier starts the journey when an event arrives on one of your inbound webhooks	No schema; fields are inferred from payloads you have already sent	Third-party systems that can post JSON to a URL but can’t call the Courier API
Twilio Segment	Courier listens to your Twilio Segment event stream and starts the journey when a matching event arrives	No schema; Courier receives whatever Segment sends	Behavioral flows driven by events you already track (page views, feature usage, lifecycle events)
Audience	Courier starts the journey when a user joins the audience you select	No schema; the trigger exposes the audience ID	Lifecycle flows keyed to who a user is rather than what they just did (trial started, plan upgraded)

API Invoke

The schema you put on an API Invoke trigger is a contract between your application and Courier, but it’s advisory rather than enforced. Courier does not reject invocations that omit schema fields. If your payload is missing a field that a node references, the journey proceeds until it reaches that node and then fails there. An accurate schema keeps things predictable and makes building in the editor much faster.

Define a Schema

Add schema fields in the trigger panel. Each field has a name and a type.

Type	Description	Example value
String	Text value	`"ORD-9042"`
Number	Numeric value (integer or decimal)	`49.99`
Boolean	True or false	`true`
Datetime	ISO 8601 timestamp	`"2026-02-10T14:30:00Z"`

Schema fields propagate as variables throughout the journey. Any downstream node (send, branch, fetch, throttle) references them as data.<field_name>, so a field named order_total is data.order_total.

API trigger with four schema fields defined: order_id (String), order_total (Number), is_first_order (Boolean), order_date (Datetime)

Invoke via API

Send a POST request to start the journey for a user. Endpoint: POST /journeys/{journeyId}/invoke The request body accepts three fields. You must provide either user_id or a profile with contact information (like an email address); data is always optional.

Field	Type	Required	Description
`user_id`	string	conditional	The recipient’s Courier user ID.
`profile`	object	conditional	Profile data for the recipient. Merged with any stored profile data for the user.
`data`	object	no	Payload data matching your schema.

curl -X POST https://api.courier.com/journeys/JOURNEY_ID/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "data": {
      "order_id": "ORD-9042",
      "order_total": 49.99,
      "is_first_order": true,
      "order_date": "2026-02-10T14:30:00Z"
    }
  }'

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "your_api_key" });

const { runId } = await client.journeys.invoke("JOURNEY_ID", {
  user_id: "user_123",
  data: {
    order_id: "ORD-9042",
    order_total: 49.99,
    is_first_order: true,
    order_date: "2026-02-10T14:30:00Z",
  },
});

console.log("Run ID:", runId);

from courier import Courier

client = Courier(api_key="your_api_key")

response = client.journeys.invoke(
    "JOURNEY_ID",
    user_id="user_123",
    data={
        "order_id": "ORD-9042",
        "order_total": 49.99,
        "is_first_order": True,
        "order_date": "2026-02-10T14:30:00Z",
    },
)

print("Run ID:", response.run_id)

The response returns a runId you can use to track the journey execution in Run Inspection.

{
  "runId": "1-67ab1234-a1b2c3d4e5f6"
}

Invoke with Profile Only

If you don’t have a stored Courier user, you can invoke with just a profile containing contact information. Courier will use the profile data to deliver messages without requiring a user ID.

curl -X POST https://api.courier.com/journeys/JOURNEY_ID/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "email": "jane@example.com"
    },
    "data": {
      "signup_source": "landing_page"
    }
  }'

const { runId } = await client.journeys.invoke("JOURNEY_ID", {
  profile: {
    email: "jane@example.com",
  },
  data: {
    signup_source: "landing_page",
  },
});

response = client.journeys.invoke(
    "JOURNEY_ID",
    profile={"email": "jane@example.com"},
    data={"signup_source": "landing_page"},
)

Profile Enrichment

When you invoke a journey with a user_id, Courier loads the user’s stored profile and merges it with any profile data you include in the request. Request fields override stored fields with the same key; stored fields not present in the request are preserved.

stored profile:  { "email": "stored@example.com", "first_name": "Jane" }
request profile: { "email": "new@example.com" }
result:          { "email": "new@example.com", "first_name": "Jane" }

Tenant-Scoped Profiles

If your application uses tenants, include the tenant ID in the profile context. Courier will load the user’s tenant-scoped profile data. You can reference tenant properties from any node in the journey. A common use is per-customer delivery settings, like the channel and credentials a send node should use for that tenant.

{
  "user_id": "user_123",
  "profile": {
    "context": {
      "tenant_id": "hospital-a"
    }
  },
  "data": {
    "appointment_time": "2026-02-15T09:00:00Z"
  }
}

cURL Preview

The journey editor writes the request for you. Click Show next to Invoke cURL in the trigger configuration panel to get the command with your journey ID and schema fields already filled in.

The Invoke cURL panel, with the journey ID and schema fields pre-filled as placeholders

Error Handling

Status	Error	Meaning
`400`	Bad Request	Missing required fields, invalid types, or no recipient identifier in the request body.
`404`	Not Found	The journey ID doesn’t exist or hasn’t been published.
`422`	Unprocessable Entity	The journey exists but can’t run. Common causes: trigger conditions not met, or the journey is archived.

Webhook

The Webhook trigger listens on an inbound webhook, so register that webhook and send it some real traffic before you build the journey. You select it by name in the trigger panel, and the editor learns the payload shape from events it has already received.

Every payload needs a userId that matches a Courier user. Courier resolves the recipient from it, and a run can’t start without one.

Configure the Trigger

Field	Required	Description
Source	Yes	The inbound webhook to listen on, selected by name.
Event	No	A single event name to narrow to. Leave it empty to start the journey on any event from that source.

The Event dropdown lists event names Courier has already received on that source, so send a few real events through the webhook before you configure the trigger. You can also type an event name that hasn’t arrived yet. Changing the Source clears the Event.

Available Data

Courier parses the JSON body and makes its fields available to downstream nodes as data.<field>. The editor infers the field list from payloads it has already received on that source, flattened up to four levels deep; anything nested deeper appears as a single object field. If you haven’t narrowed to a single event, the editor unions fields across every event recorded on that source, so a suggested field may not be present on every payload. Selecting an Event gives you a more accurate field list.

Twilio Segment

The Twilio Segment trigger connects a journey to your existing Twilio Segment event stream, so there’s no new integration code to write. Segment acts as the event bus: the same events you push to analytics, your CRM, and your marketing tools can start journeys in Courier.

The userId on a Twilio Segment track event must be a valid Courier Profile ID, or the journey won’t start.

Configure the Trigger

The Twilio Segment trigger takes one required field, Source Event. The dropdown lists the events Courier has already received from your Segment workspace, so an event has to have reached Courier at least once before it appears.

Twilio Segment trigger configuration with a Source Event dropdown showing available events from your Segment workspace

Supported Event Types

Event Type	Fires when
Track	A user performs an action (`Order Completed`, `Feature Used`, `Plan Upgraded`)
Identify	A user’s traits are updated (new email, name change, plan change)
Group	A user is added to or updated within a group

Available Data

Courier flattens the Segment event into variables for downstream nodes. Like the Webhook trigger, the editor infers the field list from events it has already received, so the hints get better once real traffic arrives.

Payload	Referenced as	Example
Top-level event fields (`event`, `type`, `timestamp`, `messageId`, `channel`)	`data.<field>`	`data.event`
Event properties	`data.properties.<field>`	`data.properties.total`
User traits	`user.<trait>`	`user.first_name`
Event context	`data.context.<field>`	`data.context.ip`

Traits are the exception. They’re exposed under user, not under data.

Audience

The Audience trigger fires on membership, not on an event you send. Audiences are dynamic, and Courier maintains membership as profiles change, so a user who newly matches the audience filter enters the journey on their own. An audience of users whose plan is trial and whose trial_ends_at falls within seven days drives a trial-expiry sequence, with users entering as their profiles change.

Configure the Trigger

Select an audience in the trigger panel. The panel shows that audience’s current member count so you can confirm you picked the right one.

Available Data

The Audience trigger exposes the selected audience’s ID as data.audience_id to every downstream node. No other audience metadata is available on the trigger context.

Trigger Conditions

Every trigger type supports optional conditions, which narrow what actually starts a journey. Conditions are evaluated before the run begins: if any condition fails, an API invocation is rejected with 422, and a webhook, Twilio Segment, or audience event is ignored. Conditions use the same operators available in branch nodes: equals, not equals, greater than, less than, contains, and more. You can reference any field in the trigger’s data context. A journey on Twilio Segment Track events could filter for data.event equals Order Completed and data.properties.total greater than 100 so it only runs for high-value orders.

Journeys’ knowledge base will automatically detect the data type for each value that can be used for conditional logic. For example, if your incoming data payload contains numbers, booleans, strings, the conditions dropdown will label your data type accordingly. The comparison operator will automatically change depending on your datatype.

Journeys will automatically detect your data type and adjust the operator accordingly.

Platform

Developer Tools

Help

Journey Triggers

API Invoke

Define a Schema

Invoke via API

Invoke with Profile Only

Profile Enrichment

Tenant-Scoped Profiles

cURL Preview

Error Handling

Webhook

Configure the Trigger

Available Data

Twilio Segment

Configure the Trigger

Supported Event Types

Available Data

Audience

Configure the Trigger

Available Data

Trigger Conditions

​API Invoke

​Define a Schema

​Invoke via API

​Invoke with Profile Only

​Profile Enrichment

​Tenant-Scoped Profiles

​cURL Preview

​Error Handling

​Webhook

​Configure the Trigger

​Available Data

​Twilio Segment

​Configure the Trigger

​Supported Event Types

​Available Data

​Audience

​Configure the Trigger

​Available Data

​Trigger Conditions

API Invoke

Define a Schema

Invoke via API

Invoke with Profile Only

Profile Enrichment

Tenant-Scoped Profiles

cURL Preview

Error Handling

Webhook

Configure the Trigger

Available Data

Twilio Segment

Configure the Trigger

Supported Event Types

Available Data

Audience

Configure the Trigger

Available Data

Trigger Conditions