> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# pan triggers: create and manage webhook triggers

> Manage webhook triggers that message or start conversations

# `pan triggers`

> [!NOTE]
>
> Added in v0.73.0.

Create, list, remove and set the signing secret of webhook triggers: secret URLs that send
an event to a conversation or start a conversation in a project. Every subcommand except
`add --inbox` works without a running dashboard; it writes `~/.overdeck/triggers.json`
directly, and the dashboard reads that file on every event. See
[Webhook triggers](https://panopticon-cli.com/configuration/triggers.md).

## add

```bash theme={null}
pan triggers add <name> (--conversation <name-or-id> | --project <key>) [options]
```

| Flag | Effect |
| - | - |
| `--conversation <name-or-id>` | Send each event as a message to this conversation. Takes a name or a numeric id; the name is stored. |
| `--project <key>` | Start a new conversation in this project for each event. |
| `--prompt <text>` | Prompt template placed before the event (required for `--project`, at most 2,000 characters). |
| `--prompt-file <path>` | Read the prompt template from a file. Do not combine with `--prompt`. |
| `--verify <kind>` | Signature check: `none` (default), `github` or `stripe`. |
| `--signing-secret <value>` | HMAC signing secret, 8-256 characters without whitespace. `github` generates one when omitted. |
| `--model <id>` | Model for conversations a project trigger starts. |
| `--harness <name>` | Harness for conversations a project trigger starts. |
| `--effort <level>` | Reasoning effort for conversations a project trigger starts. |
| `--inbox` | Also create an overdeck.ai directory inbox that holds events while this machine is offline (Anywhere plan; needs the running dashboard and `pan account login`). Prints the inbox URL instead of the Funnel lines. |
| `--json` | Print `{ trigger, hookPath, url, localUrl, funnelCommand, generatedSigningSecret }` as JSON. `url` is `null` when no `.ts.net` address is saved. With `--inbox`, it prints the dashboard's answer instead: `{ trigger, hookPath, url, urlSecretShownOnce, generatedSigningSecret, inboxUrl }`. |

Pass exactly one of `--conversation` and `--project`; otherwise it exits 1. An unknown
conversation or project exits 1. A trigger name is 1 to 64 characters: letters, digits,
spaces, `.`, `_` and `-`.

It prints the hook path, the local test URL (`http://127.0.0.1:<port>/hooks/…`), the Funnel
URL (`https://<machine>.<tailnet>.ts.net:8443/hooks/…` unless a `.ts.net` address is saved),
any generated signing secret, a `set-secret` reminder for a `stripe` trigger without a
secret, the Funnel command, and then:

```
The URL is shown once. Save it now.
```

With `--inbox`, the trigger is created through the dashboard, which asks the directory for the
inbox. It prints the inbox URL instead of the Funnel lines:

```
Created trigger trg_3f9a1c2b7d4e ("deploys") with an overdeck.ai inbox
  inbox URL:  https://connect.overdeck.ai/h/<id>

The inbox holds events for 24 hours while this machine is offline. The URL is shown once. Save it now.
```

With the dashboard not running, on a free account, signed out, or when the directory does
not answer within 10 seconds, it creates nothing and exits 1 with the reason. See
[Hold events with the directory inbox](https://panopticon-cli.com/configuration/triggers.md#hold-events-with-the-directory-inbox).

## list

```bash theme={null}
pan triggers list [--json]
```

Lists triggers with columns `ID NAME TARGET VERIFY SIGNING SECRET CREATED`. `TARGET` is
`conversation <name>` or `project <key>`; `SIGNING SECRET` is `-` for `none` triggers and
`secret set` or `secret not set` for `github` and `stripe` triggers. It never prints a
secret.

| Flag | Effect |
| - | - |
| `--json` | Print the triggers as JSON. |

With no triggers it prints:

```
No triggers. Create one with `pan triggers add`.
```

## remove

```bash theme={null}
pan triggers remove <id>
```

Removes the trigger. Its URL answers `404` from the next event on. It does not delete a
directory inbox; remove an inbox trigger in Settings → Anywhere → Triggers so its inbox is
deleted too:

```
Removed trigger <id>. Its URL now answers 404.
```

An unknown id prints `No trigger with id <id>.` and exits 1.

## set-secret

```bash theme={null}
pan triggers set-secret <id> [--secret <value>]
```

Sets the signing secret of a `github` or `stripe` trigger, for example a Stripe endpoint's
`whsec_…` secret. Without `--secret` it reads one line from standard input, so the secret
stays out of your shell history:

```bash theme={null}
pbpaste | pan triggers set-secret trg_3f9a0c1d2e4b
```

| Flag | Effect |
| - | - |
| `--secret <value>` | The signing secret. |

On success it prints `Set the signing secret for trigger <id>.` An empty value, or one that
is not 8 to 256 characters without whitespace, exits 1. An unknown id prints `No trigger
with id <id>.` and exits 1.

## Get help

Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a
[GitHub Issue](https://github.com/eltmon/overdeck/issues).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.