---
layout: docs
page_title: Triggers
description: |-
  This page covers how to use Waypoint Triggers and their various use-cases.
---

# About Waypoint Triggers

Trigger URLs are pre-configured Waypoint lifecycle operations for execution
inside Continuous Integration (CI) environments. Users can configure operations
like deploying the latest build, running a status report on all applications in
a project, running a Waypoint Up operation on all applications in a project,
and more. Trigger URLs make it easy to run Waypoint operations inside CI without
requiring the Waypoint CLI or any other Waypoint setup in your scripts. You will
simply need curl to execute a Trigger URL via HTTP.

Trigger URLs can be invoked directly inside an environment with a http request
that tells Waypoint to execute the pre-configured action. Trigger URLs
configurations are project-scoped, where their actions can operate on every
application defined in a project or target a single application inside a project.

## Waypoint Trigger CLI

The Waypoint CLI comes with a subcommand that lets you configure and update
Trigger URL configurations.

Check out our CLI docs for the `waypoint trigger` command, such as
[waypoint trigger create](/commands/trigger-create).

## Pre-configuring a Trigger URL

As an example, you can create a Trigger URL config that deploys the latest artifact
to the production workspace. First, configure the Trigger to use the
right project, application, and workspace. Then, specify which [lifecycle operation](/docs/lifecycle)
you want the trigger to execute when run. You can also include a `description` or
`tags` for extra information for the user.

```sh
$ waypoint trigger create \
      -project=hcp-packer \
      -app=backend-svc \
      -workspace=production \
      -name=deploy-latest \
      -op=deploy

Trigger "deploy-latest" (123ABC456DEF) has been created

 Trigger ID: 123ABC456DEF
Trigger URL: https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF
```

Note that creating a trigger does not validate the existence of a Project or
Application. This validation happens at execution time. If you have made a mistake
or typo, you can easily modify an existing trigger with `waypoint trigger update`.

Once a trigger has been created, you can make an HTTP request against the given
trigger URL to start and queue a job on Waypoint server.

## Modifying an existing Trigger URL Configuration

If you wish to see all of your configured triggers inside a Waypoint server,
run the `waypoint trigger list` command:

```sh
$ waypoint trigger list
» Trigger URL Configs
              ID             |         NAME         | WORKSPACE |   PROJECT   | APPLICATION |        OPERATION
-----------------------------+----------------------+-----------+-------------+-------------+---------------------------
  01FS57XXWAZRFMTSW2XVPEM41V | up-trigger           | default   | go-gitops-0 | go          | up
  01FS57Y4TC7HGQCXKM5C22VCF6 | build                | default   | go-gitops-0 | go          | build
  01FS57YBR2FB38NE08X7AWSJ52 | deploy-latest-go     | default   | go-gitops-0 | go          | deploy
  01FS57YH4TQMSP6HZ1QZ03QE2R | release-latest       | default   | go-gitops-0 | go          | release
  01FS582B3X8VW0251C1XDQ56RR | deploy-statusreport  | default   | go-gitops-0 | go          | status report deployment
  01FS58DAXTE832BM5JMG1Z2XMA | release-statusreport | default   | go-gitops-0 | go          | status report release

```

In this example, you'll configure Trigger URLs for the `go-gitops-0` project.

Now, let's say you have a _status report_ trigger that _only_ runs on your app
called `go` in the `default` workspace, but wish for that trigger to refresh the
status in the `production` workspace.

First, inspect the Trigger URL configuration to see how it's configured:

```sh
$ waypoint trigger inspect 01FS582B3X8VW0251C1XDQ56RR

» Trigger URL config:
              Name: deploy-statusreport
                ID: 01FS582B3X8VW0251C1XDQ56RR
  Last Time Active: n/a
     Authenticated: true
         Operation: status report deployment
         Workspace: default
           Project: go-gitops-0
       Application: go

```

For this trigger to run in the `production` workspace, update the
trigger's configuration:

```sh
$ waypoint trigger update -id=01FS582B3X8VW0251C1XDQ56RR -workspace=production
Trigger "deploy-statusreport" (01FS582B3X8VW0251C1XDQ56RR) has been updated
Trigger ID: 01FS582B3X8VW0251C1XDQ56RR
$ waypoint trigger inspect 01FS582B3X8VW0251C1XDQ56RR


» Trigger URL config:
              Name: deploy-statusreport
                ID: 01FS582B3X8VW0251C1XDQ56RR
  Last Time Active: n/a
     Authenticated: true
         Operation: status report deployment
         Workspace: production
           Project: go-gitops-0
       Application: go
```

For now, you can use this ID to make a request to Waypoint server to execute the
trigger.

## Running a Trigger URL Configuration via HTTP

### /v1/trigger/:trigger-id

The `/v1/trigger` endpoint takes a trigger id parameter when initiating a request.
It also accepts 3 request parameters:

- `token` (string) - For authenticated triggers, providing a token will authorize the
  request to be executed
- `stream` (string) - If stream is set to anything other than empty string, the server
  will stream back the job event stream for all queued jobs. Triggers that are not
  configured for authentication cannot stream back job event streams.
- `variables` (string map)- If set, these variables will be set as input variable overrides
  for the requested operation (i.e. set a new tag). This must be valid JSON.

### Example

In an upcoming version of Waypoint, we will provide an HTTP endpoint for easy
access to request running a configured Trigger. When you create a trigger,
you'll then see an HTTP url:

```sh
$ waypoint trigger create \
      -project=hcp-packer \
      -app=backend-svc \
      -workspace=production \
      -name=deploy-latest \
      -op=deploy

Trigger "deploy-latest" (123ABC456DEF) has been created

Trigger ID: 123ABC456DEF
Trigger URL: https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF
```

Once a trigger has been created, you can request it start via `curl` or any other
http request.

```
curl -k -G -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF
```

If your project includes an input variable that you wish to override on the request,
you can provide a `variables` option.

```
curl -k -G -d "variables={\"tag\":\"latest\"}" -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF
```

### Streaming Job Output over HTTP

When starting a trigger URL request, Waypoint server supports streaming
job output to the requester. Additionally, it supports streaming all concurrent
jobs that are running from the result of starting a trigger URL. For trigger URLs
that are not authenticated, Waypoint server does not allow for job streaming.

#### Streamed Event Types

When streaming events back from a running job, trigger URLs will return job
stream event message types depending on the kind of output from the job. A job
will be finished if it returns a `Complete` or `Error` value type.

- `Complete`
- `Error`
- `TerminalEventLine`
- `TerminalEventNamedValues`
- `TerminalEventStatus`
- `TerminalEventRaw`
- `TerminalEventStep`
- `TerminalEventTable`

#### Example

Streaming output will give you the job event streamed directly to you:

```
$ curl -k -G -d "stream=true" -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/01FTS1A6H3EH4H4W1XY89AWZ84
...
...
> GET /v1/trigger/123ABC456DEF?stream=true&token=tokenstring HTTP/1.1
> Host: waypoint.server.address.example.com
> User-Agent: curl/7.68.0
> Accept: */*
>
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Tue, 01 Feb 2022 16:55:30 GMT
< Transfer-Encoding: chunked
<
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Ref: HEAD","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Building go...","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Building Buildpack with kaniko...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Testing registry and uploading entrypoint layer","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Executing kaniko...","valueType":"TerminalEventStep"}
...
...
...
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Checking status of the Kubernetes deployment resource...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Deployment \"go-v2\" is reporting ready!","valueType":"TerminalEventStatus"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Releasing go...","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Preparing service...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Updating existing service...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Waiting for service to become ready...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Gathering health report for Kubernetes release...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Checking status of Kubernetes service resource \"go\"...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","valueType":"Complete","exitCode":"0"}
* Connection #0 to host waypoint.server.address.example.com left intact
```

Note that if you cancel watching a job stream, the job will still execute
on the server. This does not cancel the queued job.
