Skip to main content

Triggers

A trigger lets an agent act in response to an event instead of a clock. When something happens — a push to GitHub, a payment, a reading from a device — a trigger can run a task, send a notification, or both. It's how your agents react to the world in real time.

Two ways an event arrives​

Incoming webhooks. Every trigger gets its own URL. Point any external system — an automation tool, a script, a device — at that URL, and when it sends an event, your trigger fires. The data the system sends is handed to the agent, so the task can act on the specifics of what happened (a customer's email, an order number, a sensor value).

Connected-service events. When you connect an integration like GitHub, you can subscribe to its events — a new issue, a fresh comment, a push — and have them fire a trigger. You choose which events matter and filter down to just the ones you care about.

What a trigger does​

Every trigger runs at least one action:

  • Run a task — the agent does something with the event.
  • Send a notification — you (or the team) get alerted.

The event's details flow into the task automatically, so the agent's instructions can refer to the incoming data and respond to each event individually.

Personal or shared​

  • Personal triggers are automations you set up for yourself.
  • Agent (shared) triggers are team workflows, created by managers, that fire for the whole group.

Create, test, pause, resume, and delete triggers from the Triggers tab in an agent's settings, where each trigger shows its URL and recent activity. Fire a test event to confirm everything's wired up.

Getting connected-service events in​

To fire a trigger from a connected service (a new GitHub issue, say), that service has to be connected through your own OAuth app and able to deliver its events to your install. OtoDock registers each event subscription with the service for you, pointed directly at your install — so the service must be able to reach your install at its public address (see Installation).

Security notes​

  • Incoming webhooks authenticate with an API key, so only systems you've given the key can fire them.
  • Connected-service events are verified using each provider's signed-request mechanism, automatically.
Behind a login gateway?

If you run OtoDock behind a reverse proxy that forces a login on every request (Authentik, Authelia, oauth2-proxy, Cloudflare Access), let the /v1/webhooks/ path through without that login — external systems don't have a browser session, and OtoDock authenticates these requests itself. Everything else can stay behind your gateway. See Installation and the API & Webhooks page.

Next steps​