> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# How triggers work

How AgentKit triggers notify your app when something changes in a user's connected app: webhook and polling triggers, and how events are delivered.
A **trigger** tells your app when something happens in an app your users have connected, such as a new lead in Salesforce, a new activity in Pipedrive or a message that mentions your app in Slack. Scalekit sends each event to your server as a signed HTTP request, so your agent can act on it without polling the app itself.

This page explains the model: the two kinds of triggers, what you subscribe, and how events are delivered. To start receiving events, go to [Set up a trigger](/agentkit/triggers/set-up/).

> note: Triggers are in beta
>
> [Contact us](/support/contact-us/) to turn triggers on for your environment.

## How it works

You set triggers up in the dashboard, and your server receives the events:

1. **Add a delivery endpoint.** A URL on your server that receives trigger events. One endpoint can receive events from every connection in the environment, or only from the connections you choose.
2. **Subscribe.** On a [connection](/agentkit/concepts/)'s **Triggers** tab, subscribe a connected account, or the whole connection, to a trigger such as **Lead created**. Each subscription can set filters, such as a lead source or a Slack channel, and for polling triggers how often to check.
3. **Scalekit detects the change.** It either receives the event from the app or finds it by checking the app on a schedule. Which one depends on the trigger: see [Two kinds of triggers](#two-kinds-of-triggers).
4. **Your server receives a signed request.** Scalekit sends one `POST` per event to each delivery endpoint that covers the connection. Your server verifies the signature, returns a `2xx` status and hands the event to your agent.

## Two kinds of triggers

Each trigger is either a webhook trigger or a polling trigger. The **Triggers** tab tags each one **Webhook** or **Polled**, and shows whether you subscribe it **Per user** or **Per connection**.

|  | Webhook triggers | Polling triggers |
| --- | --- | --- |
| How Scalekit learns about a change | The app sends the event to Scalekit | Scalekit checks the app on an interval and sends one event per new or changed record |
| How fast events arrive | Within seconds | Up to one interval after the change, plus a few seconds |
| What you subscribe | Usually the whole connection, once | Each connected account, separately. The account must be `ACTIVE` |
| Setup in the app | Register a Scalekit URL and copy the app's signing secret into Scalekit | None |
| Examples | Slack **App mentioned**, **Message posted** | Salesforce **Lead created**, Pipedrive **Activity created or updated** |

### Webhook triggers

The app pushes events to a webhook URL that Scalekit generates for the connection. You register that URL in your own app's settings at the provider and paste the provider's signing secret into Scalekit, so it can reject forged requests. Each connector's page shows where these settings are, as in [Slack triggers](/agentkit/connectors/slack/#triggers).

The provider sends every event your app at the provider subscribes to. Scalekit delivers only the events that match a trigger subscription and its filters, and drops the rest, so subscribe your app only to the events your triggers use.

A connection-wide trigger fires once per event for the whole connection, not once per user. The event names the connection but no connected account. Your app decides which of its users, if any, should act on it.

### Polling triggers

Scalekit checks the app for each subscribed connected account, using that account's access. Each trigger has its own default and minimum interval, which the dashboard shows when you subscribe.

- **Polling starts when you subscribe.** Older records aren't sent. A record created or changed shortly before you subscribed can still arrive in the first check.
- **One event per record per check.** A record that changes several times between two checks produces one event, not one per change.
- **The interval can be longer than you asked for.** When an environment has many polling subscriptions, Scalekit can check less often to share capacity. The subscription then shows **Throttled**, and events still arrive.
- **Polling pauses when the account's access stops working.** If a user revokes access or the token can't be refreshed, the subscription shows **Credential issue — paused**. It resumes on its own once the user reconnects the account.

## Delivery

Every event reaches your endpoint as an HTTP `POST` with a JSON body, signed with the endpoint's signing secret. The body has the same shape for both kinds of triggers: which trigger fired, the connection, the connected account for per-user triggers, and the app's own record in `payload`. [Receive trigger events](/agentkit/triggers/receive-events/) shows how to verify the request and explains each field.

- **At least once.** An event can arrive more than once, for example after a retry. Each event carries a `dedupe_key`; skip one you've already handled.
- **Retried until your server accepts it.** A delivery that doesn't get a `2xx` response is retried with increasing delays.
- **Not in order.** Events can arrive out of order. Use `occurred_at` when order matters.

## Next

  - [Set up a trigger](/agentkit/triggers/set-up/): Add a delivery endpoint and subscribe to a polling or webhook trigger.
  - [Receive trigger events](/agentkit/triggers/receive-events/): Verify each request in Python or Node.js and handle repeats.


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |