Skip to content
NagentNagent
Log inSign upHire your AI Growth Team
NagentNagent
Log inSign up
All documentation

Triggers and webhooks

How outside services start work in your workspace through signed webhooks and event subscriptions, and how a client fires a trigger now MCP tokens are retired.

Browse documentation

Letting the outside world start work, without leaving the door open

Most work starts with a person in a team room. Some should start on its own: a booking made in your scheduling tool, a form filled in on your site, a message in a connected channel. Nagent lets those events in, but only when they prove where they came from, and only into your workspace.

Three things make that work:

PieceWhat it doesWhere it lives
Inbound webhook secretsLet a service post events to your workspace, signedSettings, Triggers
Apps and MCP clientsPoint a client that fires triggers to an API key or MCP sign-in, and list older MCP tokens still in useSettings, Triggers
Triggers and event subscriptionsDecide which agent does what when an event arrivesAn agent's Triggers tab, and connected tools

Open Settings, then Triggers, or go to nagent.ai/admin/settings/triggers. The page is headed Who may call your triggers from outside the workspace. and counts your webhook secrets, and your Older MCP tokens while the workspace still has some.

Inbound webhook secrets

Each secret verifies one sending service. A request is accepted only if it is signed with the secret using HMAC-SHA256 over the exact body sent.

Create one

  1. In Inbound webhook secrets, type a name. Use webhook:<source> for a service such as a scheduling or payments tool, for example webhook:calendly, or composio:<app> for a connected tool, for example composio:slack. Names use lower-case letters, numbers and dashes.
  2. Select Generate.
  3. Copy the secret from the green box straight away. "Copy this now. It will not be shown again." Then select the dismiss link.
  4. Copy the URL shown under the new entry with Copy URL, and paste both the URL and the secret into the sending service.

The list afterwards shows only a masked preview of each secret, never the secret itself. Lose it and you generate a new one.

The URL is specific to your workspace. The first secret you generate mints your workspace's endpoint; if older secrets show no URL, generating a new one makes the URL appear for every entry.

What the sending service must do

For a webhook: source:

  • Post JSON to the URL.
  • Sign the raw body with HMAC-SHA256 using the secret, as a hex digest, in an x-webhook-signature header. A sha256= prefix is accepted.
  • Put the event's name in an event or type field. Nagent records it as webhook.<source>.<event>, for example webhook.calendly.invitee.created.

A composio: source works the same way with an x-composio-signature header, and its events are recorded as tool.<app>.<event>.

A request with no signature, a wrong one, or a source with no secret is refused. There is no switch to accept unsigned calls.

Retries and repeats

Senders retry a delivery they are unsure arrived. Nagent recognises a delivery that comes again within 24 hours and starts nothing the second time, so the work happens once. It knows a delivery by the sender's own delivery id header, such as webhook-id or idempotency-key, or, when the sender sends none, by its exact body. The repeat is still answered as accepted, so the sender stops retrying.

Each trigger's rate limit per hour applies to webhook deliveries too. A delivery over the limit is recorded as rate-limited and runs nothing.

A workflow a webhook or an event starts carries the event's details with it, up to 32 KB. Larger details are left off whole, never cut part way, and the run starts without them.

Revoke

Select Revoke on an entry and confirm. The service's calls fail until you issue a new secret and update it there.

Our logic

A webhook URL that accepts anything is a way for anyone to spend your budget and start your agents. So every call must be signed, secrets are shown once, and the URL names your workspace so an event can never land in another one.

MCP client tokens

MCP client tokens are retired, and new ones are no longer made. The Apps and MCP clients card on the Triggers page says what to use instead: an API key with Fire triggers, made in API & MCP, or an MCP client connected by sign-in, which then appears under Connected apps on that page.

While the workspace still has tokens, the card lists them under Older MCP tokens, each with Revoke. They still work for now. A token acts as the person who issued it, and only for the tools it was issued for:

ToolWhat the client can do
Fire a triggerStart one of your triggers
Create an event triggerSubscribe an agent to an event
Read agent memoryRead what an agent remembers
List SEO and AEO proposalsRead your pending search and AI visibility proposals

A token stops working when the person who issued it is deactivated, leaves the workspace, or no longer holds the permission to manage tools, and a token that names no issuer has stopped already. Revoke stops a client at once. Every call is logged.

What to use instead

  • An API key, made on Settings, API & MCP. With the Fire triggers scope, a client fires triggers over MCP or the API and creates event triggers over MCP; with Read agents, it reads agent memory and lists SEO and AEO proposals over MCP. See give your developers access.
  • MCP sign-in. The client signs in to Nagent in the browser and a person approves what it may do, with no key to paste. See MCP sign-in.

Move each client to one of these, then revoke its old token.

A client fires a trigger by its id, and the trigger's rate limit per hour still applies. A trigger that is switched off or paused refuses it. For a trigger that only a client starts, pick the mcp-tool kind on the agent's Triggers tab: no schedule or event fires it.

Triggers: what fires an agent

A secret only gets an event in. What happens next is decided by a trigger, which belongs to an agent. Open the agent in the Agent Workbench and choose its Triggers tab.

A trigger names a label, an action key, a rate limit per hour, and how it fires. What the agent does when it fires is the trigger's What the job does (see below). A workflow has triggers of its own, on the workflow's page rather than on an agent: a schedule, an event, a webhook or a team thread; see building a workflow. The two kinds most useful here:

  • event fires on a named event, such as webhook.calendly.invitee.created or lead.replied. Events are checked about every five minutes, in every workspace. Each event fires a trigger once, and an event from before the trigger was made never fires it.
  • cron fires on a schedule, with presets and a preview of the next run. A schedule keeps the time zone it was saved in, daylight saving included. Schedules are also checked about every five minutes, so a run can start a few minutes after its time, and never runs twice for the same time.

Every fire is checked against the agent's trust level and policies, the same check a lead's own jobs get, before any work starts. An event can never make an agent do something it could not have done anyway. A workflow's trigger is logged on Actions; an agent's trigger records each fire under Recent fires on its Triggers tab.

Actions, listing recent firings with their trigger, agent, cost and resolution

What a fire does today

Each of an agent's triggers has its own Runs as a room job switch, and nothing else decides whether a fire starts work. With it on, "each fire starts a room job for this agent in its team room. The room lead reviews the work and posts the result in the thread." With it off, "a fire records a skip and starts nothing": the fire is recorded as skipped-disabled, never as fired, and is not counted in the trigger's fires.

The switch is off on every agent trigger saved before this release. None of them starts work until an admin opens its Room job settings and switches it on. A new trigger starts with the switch off too.

A fire can also start nothing because the agent's work needs a person's approval, the room has no lead, or the workspace already has 4 room jobs running. Recent fires says which. For the switch, the room settings and what each message means, see an agent's triggers.

Events from connected tools

When a tool connected through Composio reports an event, such as a new Slack message, it fires your workspace's composio-webhook triggers that name that app:

  • The app matches whatever its capitals, so Slack and slack are the same app.
  • A trigger with no event runs on every event from the app. One with an event runs on that event only.
  • The same event delivered twice fires each trigger once.

The event's details go into the job's task, as with a webhook.

Events from your pipeline

Besides webhooks and connected tools, Nagent raises events of its own when something happens in your pipeline. A trigger can name any of these:

EventWhen it fires
lead.repliedA reply to your outreach is matched to the e-mail it answers
signal.flaggedA lead is flagged for a high-attention signal
lead.closed-wonA lead reaches a won stage in your pipeline
lead.closed-lostA lead reaches a lost stage in your pipeline
room.job.acceptedA room lead accepts an agent's room job, or a person accepts a workflow run at its review. This is what a chain listens for

The event carries which lead or company it is about and, for a reply, how the reply was classified. It never carries the reply's text. Won and lost follow the kind of stage, so they still fire after you rename your stages.

To pick one on an agent's Triggers tab, choose the event kind and open Browse canonical event names under Event name. The list is grouped by where the event comes from, and each name is followed by what it means: lead.replied reads "A Lead replied to outreach", and signal.flagged reads "An operator or agent flagged a high-attention signal". On a workflow, the editor's panel headed Triggers · what can start this takes the same names under the Event kind; see building a workflow.

Two prebuilt workflows in the NORA team room start on these events once their schedule is switched on. Their cards read Keep running: When a lead replies for Follow-up sequence and Keep running: When a signal is flagged for Signals on a named account. See workflows in a room.

Event subscriptions on connected tools

When a connected tool reports an event, such as a Slack message or a Gmail thread, an event subscription decides which agent action runs. A subscription matches an event pattern, can filter on the event's details, and fires its action through the same approval rules as everything else.

The Workspace set-up page has an Event subscriptions card: "What fires an agent when something happens in a connected tool." It counts your subscriptions and flags any that are failing, because "a failing subscription is worse than none: it is a silence somebody believes is a trigger."

Workspace set-up, whose rail lists Event subscriptions as Not started with nothing subscribed yet

There is no screen for creating event subscriptions yet; the card's link opens the tools page, where triggers on each connected tool can be reviewed (see Third-party tools). To set a subscription up, ask the Nagent team in your team room, and say which of the event's details the action needs: a subscription passes its action only the details it names, and nothing else from the event.

The tools page with no tools connected yet, and Browse all tools and Connect a tool

Who can do this

Opening the Triggers page needs tool read permission. Generating or revoking secrets, and revoking old MCP tokens, needs tool write permission, and without it the page says it is read only. Creating an agent's triggers needs permission to edit AI teams. An Organisation admin holds all of these.

Where to go next