> For the complete documentation index, see [llms.txt](https://documentation.pushly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.pushly.com/platform/journeys/external-event-triggers.md).

# External Event Triggers

Start a journey the moment your own systems report something that matters — a severe weather alert, a flight delay, a final score — and put the event's details in the message

## External Event Triggers

An **External Event** trigger starts a journey when your own systems tell Pushly that something has happened: a severe weather warning is issued, a flight is delayed, a team wins. You choose which kind of event the journey listens for, can narrow it to only the events that matter, decide which subscribers it reaches, and can put the event's own details straight into the notification.

Where other triggers react to what a subscriber does on your site, an External Event trigger reacts to what happens in the world your business already knows about — so the message can say "Severe thunderstorm warning for your area until 9 PM" rather than send a generic reminder afterwards.

### Before you start: connecting your system

External events are sent to Pushly by your own systems, so a developer on your team must first connect them to send events to your domain. The technical details are in the [Pushly developer documentation](https://developers.pushly.com/reference/using-the-external-events-api).

Each event your system sends has a name (its **event type**, such as `weather_alert` or `flight_delayed`), and can carry **properties** — the details of that particular event, such as a headline, a severity, a flight number or an affected area. Each event also says who it is for: either the specific subscribers it names, or every subscriber who qualifies for a journey listening to it.

There is nothing to set up in the platform beforehand. **An event type appears in the Event type picker automatically the first time your system sends that event**, together with the properties it carried. Properties added later are picked up the same way. Until the first event arrives, the picker is empty.

### How It Works

#### 1. Choose the trigger and event type

When creating a triggered journey, on the **Configuration** tab:

1. In the **Trigger** section, open **Subscribers enter this journey after** and choose **an external event is received for them**.
2. In the **External Event** section that appears, choose the **Event type** the journey should listen for.

If no event types are listed yet, your system has not sent its first event. See [Before you start](#before-you-start-connecting-your-system).

#### 2. Restrict which events trigger the journey (optional)

By default, every event of the chosen type starts the journey. To react to only some of them, switch on **Restrict events that trigger this journey based on the event's properties** and add conditions over the event's properties — for example, only alerts whose `severity` is *Severe*.

* This check runs on the event itself, before any audience is worked out. Events that do not match are ignored entirely.
* **A condition on a property the event did not carry, or carried as empty, is treated as not met.** The rest of the restriction still decides: an event with no `category` does not pass "category is not *test*" on its own, but still passes "category is not *test*, or priority is *high*" when its priority is high.
* If you switch the restriction on, add at least one condition, or turn it off again. The journey cannot be saved with the switch on and no conditions.

#### 3. Choose who enters: Entry Criteria

To limit which subscribers enter, go to **Entry Criteria** in the **Audience** section and switch on **Restrict entry to this journey based on subscriber attributes, which may be compared against the triggering event.** It uses the same condition builder as the segment screen, with the same fields, operators and controls, including custom profile attributes.

Wherever a field takes a value, you can choose where the value comes from:

* **Value** — a fixed value you enter, as on the segment screen.
* **Event property** — a property of the event that triggered the journey. For example, compare the subscriber's city to the event's `city`, or target subscribers whose location falls inside an area the event carries.

An area supplied by an event must be a list of at least three points (longitude and latitude pairs). An event that carries an area in any other shape is not routed to that journey. Your developer can confirm the format.

If a journey's entry criteria use a property that a particular event did not carry, that journey does not receive that event. Other journeys listening for the same event type are unaffected.

#### 4. Use the event in the message

Event properties are available as macros in the journey's notifications, offered as their own group in the macro picker. For example:

* `{{event.properties.headline}}` — any property the event carries
* `{{event.name}}` — the event type's name
* `{{event.occurred_at}}` — when the event happened

**A notification that needs a property an individual event did not carry, or carried as empty, is not sent** for that event, rather than being sent with a gap in it. If a message uses a property the event type has not yet been seen to carry, the builder warns you.

### What to Expect

* **Frequency caps and entry rules still apply.** An event can only start a journey for a subscriber who is eligible for it, exactly as with any other trigger — including the journey's **Subscriber Entry Cap** and audience settings.
* **The journey only hears events during its run dates.** Events that arrive before the journey's start date, or after its end date or completion, do not start it.
* **Events have a relevance window.** By default an event is relevant for 24 hours from when Pushly receives it, unless your domain is set up with a different window or the event itself carries its own expiry time. The window cannot be set per event type. An event that arrives too late to matter is ignored.
* **An event that lapses during a delay ends the journey.** If the relevance window passes while a subscriber is waiting on a delay step, their journey ends there without sending, so a later event can bring them back in.
* **Changes take a few minutes to reach live routing.** After you save a journey — or activate, pause or change one — allow about ten minutes before new events are routed according to the change.

### Scenarios

#### Severe weather to an area

A weather service sends a `weather_alert` event for every warning it issues, carrying a `severity`, a `headline`, an `expires` time and the affected `area`.

* **Trigger:** **an external event is received for them**, **Event type** `weather_alert`.
* **Restrict events:** `severity` is *Severe*.
* **Entry Criteria:** the subscriber's location is within **Event property** `area`.
* **Message:** `{{event.properties.headline}} — in effect until {{event.properties.expires}}.`

Only subscribers inside the warned area receive it, and only for severe warnings.

#### Flight delay to named passengers

An airline sends a `flight_delayed` event naming the passengers on the flight, with `flight_number`, `new_departure` and `gate` properties.

* **Trigger:** **Event type** `flight_delayed`, with no restriction.
* **Entry Criteria:** left off — the event already names its passengers.
* **Message:** `Flight {{event.properties.flight_number}} now departs at {{event.properties.new_departure}} from gate {{event.properties.gate}}.`

If an event arrives without a `gate`, no notification is sent for it rather than one with a blank gate.

#### Sports team followers

A sports publisher sends a `game_final` event for every finished game, with `team`, `opponent` and `score` properties.

* **Trigger:** **Event type** `game_final`.
* **Restrict events:** `team` is *Wildcats*, to keep this journey to one team.
* **Entry Criteria:** the subscriber's favourite-team profile attribute equals **Event property** `team`.
* **Message:** `Final: {{event.properties.team}} {{event.properties.score}} vs {{event.properties.opponent}}.`

### Benefits

* Reach subscribers at the moment something happens, not on the next scheduled send
* Put the event's own details — the headline, the flight number, the score — in the notification
* Aim each event at the subscribers it names, or at everyone in the area or group it concerns
* Ignore the events that do not matter, without any change to the system sending them
* No platform setup before the first event: event types and their properties register themselves

For an overview of triggered journeys and the rest of the journey configuration, see [Journeys](https://documentation.pushly.com/platform/journeys) and [Journey Builder](https://documentation.pushly.com/platform/journeys/journey-builder.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.pushly.com/platform/journeys/external-event-triggers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
