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 editors and managers, that fire for the whole group. Their notifications reach only the people who use that agent.

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 (you need to be able to edit the trigger to do that).

Getting connected-service events in​

To fire a trigger from a connected service (a new GitHub issue, say), that service has to be connected 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). You subscribe from the account's card under User Settings → Integrations.

A GitHub subscription can cover a single repository, or every repository in an organization. For a whole organization, the connected account needs GitHub's Organization webhooks permission.

An agent can also subscribe on its own behalf, and its shared triggers and shared apps need exactly that. A manager of the agent sets it up under Agent Settings → MCPs, beneath the account the agent's tool uses, or from the account's card with Subscribe as and the agent's name. Your own subscriptions feed your personal triggers, and the agent's subscriptions feed its shared ones.

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.
  • Events are capped at 2 MB, or 25 MB for signed GitHub events and webhooks sent with a valid API key. Anything larger is refused with HTTP 413.
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​