Set up a trigger

Set up a trigger in the Scalekit dashboard so your server receives an event each time something changes in a user’s connected app. You add a delivery endpoint once per environment, then subscribe to triggers on each connection. Polling triggers and webhook triggers need different setup: follow the section for the kind you picked.

New to triggers? How triggers work explains the two kinds and how events are delivered.

• Triggers turned on for the environment.
• A connection for the app, such as Salesforce or Slack.
• The Admin or Developer role. See Team members and roles.
• A server with a public HTTPS URL that accepts POST requests. While you develop, a tunnel to your local server works.
• For a polling trigger: a connected account in ACTIVE status on the connection. Authorize a user shows how to create one.
• For a webhook trigger: access to your own app’s settings at the provider, such as your Slack app.

A delivery endpoint is the URL on your server where Scalekit sends trigger events. An endpoint can receive events from every connection in the environment, or only from the connections you choose, so you can send different apps’ events to different endpoints.

1. In the Scalekit dashboard, select the environment, then open Developers > Trigger Delivery and select Add endpoint.

2. Enter your Endpoint URL, for example https://example.com/scalekit/triggers, and an optional Description.

3. Under Receives events from, choose All connections, or Only these connections and pick the connections. You can change this later without registering the endpoint again.

4. Select Save endpoint.

5. In the endpoints table, select Reveal under Signing secret, then copy the secret. It starts with whsec_. Store it with your other server secrets, for example as SCALEKIT_TRIGGER_SECRET, and never expose it to a browser.

Each environment has its own endpoints and secrets. Add an endpoint in Production too when you go live.

Open AgentKit > Connections, select the connection, then open the Triggers tab. It lists the triggers the connector offers, each tagged:

• Webhook or Polled: how Scalekit learns about changes.
• Per user or Per connection: whether you subscribe each connected account or the connection once.

Select Show details on a trigger to see Requires, the scopes the connection must grant for the trigger to work, and for a polling trigger Cadence, its default and minimum interval.

Above the list, a setup card shows the steps this connection still needs, such as generating a webhook URL or connecting an account. Once they’re done, it shrinks to a Setup complete line with a Manage button.

Polling triggers need no setup in the app. Subscribe each connected account whose changes you want.

1. On the Triggers tab, select Subscribe next to the trigger, such as Lead created in Salesforce or Activity created or updated in Pipedrive.

2. Pick the connected account. To subscribe several at once, select Subscribe several accounts and pick them. An account that can’t receive the trigger, for example because it isn’t ACTIVE, shows why and isn’t added.

3. Optional: fill in the trigger’s filters, such as a lead source. Leave a filter empty to receive every matching record. Each distinct set of filter values is a separate subscription.

4. Optional: set Check interval (seconds). It defaults to the trigger’s default interval, and an interval below the trigger’s minimum is refused.

5. Select Subscribe.

The first check runs shortly after you subscribe, then once per interval. Records created or changed before you subscribed aren’t sent, except ones changed shortly before, which the first check can pick up.

Webhook triggers need three things from your app at the provider: Scalekit’s webhook URL registered as the event destination, the provider’s signing secret saved in Scalekit, and a subscription to the provider’s events the trigger uses. The setup card on the Triggers tab walks you through them in order. Each provider names these settings differently: the connector’s page lists where they are, as in Slack triggers.

1. Generate the webhook URL. In the setup card, select Generate webhook URL. The URL is unique to this connection.

2. Paste the provider’s signing secret. Copy the signing secret from your app’s settings at the provider. In the setup card, select Set signing secret, paste it and select Save.

   Save the secret before you register the URL. Some providers check the URL as soon as you paste it, and Scalekit needs the secret to answer that check.

3. Register the URL with the provider. Copy the URL from the setup card and paste it into your app’s event or webhook settings. If the provider checks the URL, Scalekit answers for you.

   Then subscribe your app at the provider to the events the trigger needs. The connector’s page lists them. Subscribe only to those: events that match no trigger subscription aren’t delivered to your endpoint.

4. Confirm the registration. Back in the setup card, select I’ve registered it. Scalekit can’t see the provider’s settings, so this step is marked done only when you confirm.

5. Subscribe. Select Subscribe next to the trigger. A Per connection trigger has no account to pick. Optional: fill in the trigger’s filters, such as a channel, to receive only matching events. Then select Subscribe.

Events from the provider now reach your delivery endpoint within seconds.

When you rotate the signing secret at the provider, update it in Scalekit without dropping events:

1. Open the connection’s Triggers tab, select Manage on the Setup complete line, then select Replace signing secret.

2. Paste the new secret and select Save. Scalekit now accepts events signed with either the previous or the new secret. The card shows when the previous secret stops being accepted.

3. Update the secret at the provider.

4. Select Confirm rotation, and confirm. From then on, Scalekit accepts only the new secret, and rejects events signed with the previous one.

There’s no test event to send, so make a real change:

• Polling trigger: create or change a matching record in the app, such as a new lead in Salesforce or a new activity in Pipedrive, in the subscribed user’s account. Wait up to one interval.
• Webhook trigger: do what the trigger watches for in the app, such as mentioning your app in a Slack channel it’s in.

Then open Developers > Trigger Delivery. Under Recent delivery attempts, the event appears with your server’s response code. A 2xx code means your server accepted it. To handle the request in your server, see Receive trigger events.

The account picker shows why next to the account. The common reasons:

• The account’s credential has expired: ask the user to reconnect, as in Handle inactive accounts, then subscribe again.
• The account hasn’t finished connecting: the user hasn’t completed the authorization link. Wait until the account is ACTIVE.
• The account’s grant doesn’t cover a scope the trigger requires: add the scopes listed under Requires to the connection, then ask the user to reconnect so they grant the new scopes.

• Check that an endpoint covers the connection: the setup card on the Triggers tab shows how many delivery endpoints cover it. An endpoint set to Only these connections must include this connection.
• Check Recent delivery attempts on Developers > Trigger Delivery. A non-2xx code or No response means the request reached your server, or tried to, and failed there.
• For a polling trigger, wait a full interval after the change, and check that the change matches the subscription’s filters.
• For a webhook trigger, check that the provider shows the URL as verified and that your app at the provider subscribes to the right events.

Save the provider’s signing secret in Scalekit first, then register the URL again. Scalekit answers the provider’s check only once it has the secret.