Skip to main content
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.
1

Create the binding

For the github provider, --event, --org, and --repo build the trigger source for you. Omit --repo for an org-wide binding.
--webhook-secret - reads the secret from stdin, keeping it out of your shell history. To reuse a secret you already store:
For a non-GitHub source, use --provider generic_webhook and set --trigger-source yourself.
2

Get the webhook URL

Paste this into the source system’s webhook settings, along with the same secret you set.
3

Send a signed test

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

Confirm it landed

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:

​
Mapping event data into the run

Use --input-mapping to shape the incoming payload into the agent’s input:
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:
To remove it for good:

​
Choosing the run environment

By default a triggered run uses the agent’s current stage. To pin a trigger to a specific environment regardless:
This is useful while you’re still confirming the mapping is right — the webhook fires end to end, but nothing takes effect.

​
See also