How triggers work

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.

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’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.
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.

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

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.

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.

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.

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 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.