> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Run an agent from an external event — webhook bindings, HMAC signing, and the event record.

A trigger binding connects an external event to an agent run. When a matching event arrives, the platform starts a run of the bound agent.

```mermaid theme={null}
flowchart LR
    A[External system] -->|signed webhook| B[Trigger binding]
    B --> C[Trigger event recorded]
    C --> D[Agent run]
```

## Bindings

A binding names the agent to run, the provider the event comes from, the trigger type, and the source that identifies which events match.

For GitHub, you describe the source in parts and the platform assembles it:

```bash theme={null}
jstm triggers create \
  --agent-id security-review \
  --name "Pull request opened" \
  --provider github \
  --trigger-type webhook \
  --event pull_request --org acme-corp --repo platform \
  --webhook-secret -
```

Omitting `--repo` makes the binding org-wide. For other systems, use `--provider generic_webhook` and set `--trigger-source` directly.

## Signing

Webhook deliveries are verified with an HMAC secret. You either create one when the binding is created, or point at a credential you already hold:

| Option                       | Behavior                                                     |
| ---------------------------- | ------------------------------------------------------------ |
| `--webhook-secret <value>`   | Creates a vault credential holding the secret                |
| `--webhook-secret -`         | Reads the secret from stdin, keeping it out of shell history |
| `--vault-credential-id <id>` | Uses an existing vault credential                            |

`jstm triggers test` sends a test delivery signed by the server using the real secret. The secret never leaves the backend, so the test exercises the true signature path rather than a mock.

## Input mapping

An incoming payload rarely matches an agent's declared inputs. `--input-mapping` bridges them:

```bash theme={null}
jstm triggers create … --input-mapping '{"repo":"$.repository.full_name","pr":"$.number"}'
jstm triggers create … --input-mapping @mapping.json
```

## Environment override

By default a triggered run uses the agent's current stage. An override pins it:

```bash theme={null}
jstm triggers update 3f21b8c0-… --environment-override dry_run
```

This is how you exercise a live webhook end to end while nothing takes effect — useful while confirming the mapping is right.

## Events

Every delivery is recorded, whether or not it produced a run.

```bash theme={null}
jstm triggers events --binding-id 3f21b8c0-…
jstm triggers events --outcome failed --limit 100
jstm triggers event 7ac1d3f5-…
```

This is the first place to look when a webhook fired but nothing happened. The event record distinguishes "never arrived" from "arrived and was rejected" from "arrived and started a run that failed" — three very different problems.

## Enabling and disabling

Disabling preserves the binding, its secret, and its event history:

```bash theme={null}
jstm triggers update 3f21b8c0-… --disabled
jstm triggers update 3f21b8c0-… --enabled
```

Prefer this to deleting when the pause is temporary.

## See also

* [Trigger an agent](/guides/trigger-an-agent) — walkthrough.
* [`jstm triggers`](/cli/triggers) — full reference.
* [Scheduling agents with cron](/features/scheduling) — for time-based runs.