> ## 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.

# Trigger an agent

> Run an agent from an external event — create a webhook binding, test it, and inspect deliveries.

A trigger binding connects an external event to an agent run. This guide sets up a GitHub webhook, but the same shape works for a generic webhook from any system.

## Prerequisites

* An agent that runs correctly on its own. Test with `jstm agent run` first.
* Permission to add a webhook in the source system.

<Steps>
  <Step title="Create the binding">
    ```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 -
    ```

    For the `github` provider, `--event`, `--org`, and `--repo` build the trigger source for you. Omit `--repo` for an org-wide binding.

    <Tip>
      `--webhook-secret -` reads the secret from stdin, keeping it out of your shell history. To reuse a secret you already store:

      ```bash theme={null}
      jstm triggers create … --vault-credential-id 4d90c7e2-…
      ```
    </Tip>

    For a non-GitHub source, use `--provider generic_webhook` and set `--trigger-source` yourself.
  </Step>

  <Step title="Get the webhook URL">
    ```bash theme={null}
    jstm triggers webhook-url 3f21b8c0-91ad-4f6e-89b2-77c0a4e1d9f3
    ```

    Paste this into the source system's webhook settings, along with the same secret you set.
  </Step>

  <Step title="Send a signed test">
    ```bash theme={null}
    jstm triggers test 3f21b8c0-91ad-4f6e-89b2-77c0a4e1d9f3
    ```

    The server resolves the vault credential and signs with the real HMAC secret, so this exercises the true signature path rather than a mock. No secret leaves the backend.
  </Step>

  <Step title="Confirm it landed">
    ```bash theme={null}
    jstm triggers events --binding-id 3f21b8c0-91ad-4f6e-89b2-77c0a4e1d9f3
    jstm triggers event 7ac1d3f5-0b62-4e19-92c8-5f6ab0e2d411
    ```

    Events show what arrived and what the platform did with it. This is where to look when a webhook fired but no run started.

    Then check the run itself:

    ```bash theme={null}
    jstm agent runs security-review
    ```
  </Step>
</Steps>

## Mapping event data into the run

Use `--input-mapping` to shape the incoming payload into the agent's input:

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

The `@file` form keeps a long mapping out of the command line.

## Turning a trigger off

Disable rather than delete when the pause is temporary. The binding, its secret, and its event history survive:

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

To remove it for good:

```bash theme={null}
jstm triggers delete 3f21b8c0-… --confirm
```

## Choosing the run environment

By default a triggered run uses the agent's current stage. To pin a trigger to a specific environment regardless:

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

This is useful while you're still confirming the mapping is right — the webhook fires end to end, but nothing takes effect.

## See also

* [Triggers](/features/triggers) — how bindings behave.
* [`jstm triggers`](/cli/triggers) — full reference.
* [Schedule an agent](/guides/schedule-an-agent) — for time-based runs instead.