Guide

Responsibility triggers

Start a responsibility when something happens elsewhere: an event sent to its trigger address, signed so only the real sender gets through, filtered to the events that matter, and shaped into the message your Bot receives.

4 min read

Adding a triggerCopy link to this section

  1. Open Responsibilities and find the responsibility. Its card has a Triggers section; press Add trigger.
  2. Choose the kind of Trigger: Webhook for any service that can send one, or GitHub, Linear, Sentry, PagerDuty, Email or Slack.
  3. Set the filter (below) and save. Each HTTP trigger shows the address to send to under POST to, with Copy URL.

Triggers belong to the person whose responsibility they start: each person sees and changes only their own. A trigger on a paused or completed responsibility acknowledges events but never starts a run.

How deliveries are signedCopy link to this section

The address alone lets nobody in: every delivery must prove it comes from the sender. A Webhook or GitHub trigger is given its own key when it is made; Show key, Copy key and Copy header give it to the sender. For the other kinds, paste the signing secret the sending service shows you; until then the trigger says Waiting for the signing secret and refuses deliveries.

On a Webhook trigger, Sender picks the service that sends it, so its own signing scheme, event field and delivery id are used; Any sender, signed with this deployment's key accepts a bearer key or a signature with a timestamp. A signed delivery whose timestamp is too far from now is refused as a replay: Timestamp tolerance (seconds) sets how far, from 30 to 3600 seconds, and 300 by default.

Rotate key makes a new key. Keep the old key working for lets the old one carry on for up to a week while you update the sender; Stop accepting the old key ends that early. Rotations are recorded in the audit trail.

Tip

Under Who may send, Accepted addresses limits a Webhook trigger to the addresses or ranges you list, and Largest event (KB) refuses anything bigger. Both are checked before the signature.

Filter conditionsCopy link to this section

Each trigger has one filter, checked in this order:

  • Event types: a comma-separated list. Leave it empty for every event. An entry also matches its sub-types, so issues matches issues.opened.
  • Only when field … equals: one field of the event that must have a given value, compared without regard to case.
  • Condition (CEL, optional): a rule over event.type and event.payload that must be true, set when the trigger is added. A field the event does not have counts as no match.

Test against the last event checks the condition against the newest stored event and tells you whether it would start a run, changing nothing. Max runs per hour caps how often the trigger may start a run; deliveries over the cap are acknowledged and dropped. A redelivery of the same event is not run twice.

Field mappingCopy link to this section

Without a Prompt template, the Bot receives the whole event. With one, it receives only the message you write, with placeholders such as {{issue.title}} filled from the event's fields. Fields from the last real event lists the fields of the newest signed delivery, and each can be inserted with one click. Preview shows the message as the Bot will get it.

Instruction for this trigger (optional) is added after the responsibility's own instruction whenever this trigger fires, so two triggers on one responsibility can ask for different things. A Webhook trigger can also hold a Payload schema: a delivery that does not match it is refused before anything runs.

Warning

What arrives in an event is always passed to the Bot as untrusted content, so text in a payload cannot give it new instructions.

Testing and the delivery logCopy link to this section

Send test delivers a sample event, or the Test payload (JSON, optional) you paste, without a signing key. It starts a real run: the Bot is told the event is test data, but it has its usual tools.

Recent deliveries shows the last 20 deliveries to a trigger: whether the signature verified, the answer the sender got, what happened (for example Filter did not match or Duplicate, not run again) and a link to the run it started. Header values that carry credentials are hidden.

Replaying an eventCopy link to this section

Under View runs, Replay delivers a run's event again as a new run, for example after you fixed the instruction. The original run stays as it was; the new one is marked Replay with a link to see the original run. A responsibility can replay up to 10 events an hour, only while it is active, and each replay is recorded in the audit trail.

To start work on a schedule instead of an event, see Routines and responsibilities.

Last updated