A trigger is what starts your Agent when you're not there. An Agent can have as many as you need.
Go to Agent → open an Agent → Manage → Triggers → Create trigger. When you create a trigger, its page opens so you can finish setting it up.
What kinds of trigger are there?
| Trigger | What it does |
|---|---|
| Scheduled | Runs the Agent on a repeating schedule, in the timezone you pick |
| Webhook | Runs the Agent whenever another system sends something to a private web address |
| Integration | Runs the Agent when something happens in an app you've connected |
How do I schedule an Agent?
Add a Scheduled trigger, set when it should run, and pick a timezone. Hercules repeats the schedule back to you in plain English, so you can check it before saving.
Give it a name if you like, for example Weekday morning digest.
Add a Message to tell the Agent what to do on each run, for example Post yesterday's signups and churn in #growth. Leave it empty and the Agent follows its instructions. Either way, each run tells the Agent the date and time it's for.
How do I use a webhook trigger?
Add a Webhook trigger. Its page opens once it's created: copy the web address from there. Have the other system POST its event to that address, and each POST starts a run the Agent can read the event from. Other kinds of request don't start anything.
Add a Message to tell the Agent what to do with each event. Insert values from the event with {{ }}, for example New order {{ data.id }} totaling {{ data.total }}. Leave it empty to pass the whole event. Integration triggers have the same Message field.
Anyone with the address can start your Agent, so keep it secret. Treat it like a password.
How do I start an Agent from a Linear issue?
Point a Linear webhook at a Webhook trigger, then tell the trigger which issue changes count.
Add the trigger
Add a Webhook trigger. Its page opens once it's created: copy the web address from there.
Create the Linear webhook
In Linear, open your workspace settings, go to API, and create a webhook. Paste the address, pick the team, and select Issues. Copy the signing secret Linear shows.
Check the signature
Back on the trigger's page, set Verification to Linear and paste the signing secret. Hercules then rejects any request Linear didn't sign, and starts one run per Linear event even when Linear sends it again.
Choose which changes start a run
Add conditions under Only run when. To run when an issue gets the
hercules-botlabel:data.labelIdscontains the label's IDupdatedFromcontainslabelIdsupdatedFrom.labelIdsdoes not contain the label's ID
To run when an issue is assigned to a user, use
data.assigneeIdis the user's ID, andupdatedFromcontainsassigneeId. Find both IDs in the first event the trigger receives.Write the message
For example
Work on {{ data.identifier }}: {{ data.title }}. {{ data.description }} Issue: {{ url }}.
Without the updatedFrom conditions, every later edit to a labeled or assigned issue starts another run.
How do I start an Agent from another app?
Search the trigger catalog for the app, for example Stripe or Linear. Filter by Connected to see only the apps your Organization has already set up. Pick the app, then choose which events should start a run.
For GitHub you pick the repository from a list rather than typing it, and you can type one in if it isn't there. If the connection fails, the trigger tells you why.
If the app you need is missing, click Suggest a trigger.
Additional FAQ
How do I see what a trigger actually did?
Open Run history. Every run names the trigger behind it, and webhook runs also show what was sent to them.
How do I stop an Agent running?
Switch the trigger off. Each one has its own toggle, so you can pause a schedule and leave the rest running, then switch it back on later without setting it up again. Deleting it works too. Channels have the same toggle.
How do I find out when a triggered run fails?
By email. When a run started by a schedule, a webhook, or a connected app fails or stops at its step limit before it finishes, the person the run executed as gets an email with a link to the run. Hercules sends at most one a day per Agent, and it counts the runs that failed in between. To turn it off, go to Manage → Agent settings and switch off Failure emails.
Can a scheduled run go on forever?
Not if you set a limit. Manage → Agent settings → Run limits caps how long a single run can take and how much it can spend. See Costs and limits.
Can I test a trigger before relying on it?
Test the Agent itself in the test chat first, so you know the instructions work. Then add the trigger and check the first real run under Runs.
What is the difference between a trigger and a channel?
A trigger starts a run from a clock or an event. A channel starts a run because a person @-mentioned the Agent in Slack, GitHub, Linear, or another chat tool, and the Agent replies to them there.