Receive trigger events

Each time a trigger fires, Scalekit sends your delivery endpoint an HTTP POST with the event as JSON. Your server verifies the signature, returns a 2xx status quickly and hands the event to your agent. This page shows a handler in Python and Node.js, how to handle repeats and retries, and what each field in the event means.

• A delivery endpoint and its signing secret, from Set up a trigger. The code below reads the secret from SCALEKIT_TRIGGER_SECRET.
• Your Scalekit API credentials in SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID and SCALEKIT_CLIENT_SECRET, as in the Quickstart. The SDK client verifies the signature.

Scalekit signs every request with the endpoint’s secret. Verify the signature against the raw request body before you trust the event, so a forged request can’t make your agent act. The SDK checks the webhook-id, webhook-timestamp and webhook-signature headers and rejects requests more than five minutes old. Then parse the body as JSON.

pip install scalekit-sdk-python fastapi uvicorn

1
import json
2
import os
3

4
from fastapi import FastAPI, Request, Response
5
from scalekit import ScalekitClient
6
from scalekit.common.exceptions import WebhookVerificationError
7

8
scalekit_client = ScalekitClient(
9
    os.environ["SCALEKIT_ENVIRONMENT_URL"],
10
    os.environ["SCALEKIT_CLIENT_ID"],
11
    os.environ["SCALEKIT_CLIENT_SECRET"],
12
)
13
app = FastAPI()
14
handled = set()  # use your database in production
15

16

17
@app.post("/scalekit/triggers")
18
async def scalekit_trigger(request: Request):
19
    body = await request.body()  # the exact bytes Scalekit signed
20
    try:
21
        scalekit_client.verify_webhook_payload(
22
            os.environ["SCALEKIT_TRIGGER_SECRET"], request.headers, body
23
        )
24
    except WebhookVerificationError:
25
        # A bad or missing signature, or a request older than five minutes
26
        return Response(status_code=400)
27
    event = json.loads(body)
28

29
    # Retries repeat an event. Key on dedupe_key plus the account you act as.
30
    key = (event["dedupe_key"], event["connected_account_id"])
31
    if key in handled:
32
        return Response(status_code=204)
33

34
    if event["delivery_scope"] == "account":
35
        print(f"{event['trigger_type']} for {event['connected_account_id']}: {event.get('resource_id')}")
36
    else:
37
        # A connection-wide event names no account: your app decides who acts on it
38
        print(f"{event['trigger_type']} on {event['connection_id']}: {event.get('resource_id')}")
39
    # Start your agent in a background job here, then respond
40

41
    handled.add(key)
42
    return Response(status_code=204)

npm install @scalekit-sdk/node express
npm install --save-dev tsx @types/express

1
import express from 'express';
2
import { ScalekitClient, WebhookVerificationError } from '@scalekit-sdk/node';
3

4
const scalekit = new ScalekitClient(
5
  process.env.SCALEKIT_ENVIRONMENT_URL!,
6
  process.env.SCALEKIT_CLIENT_ID!,
7
  process.env.SCALEKIT_CLIENT_SECRET!,
8
);
9
const app = express();
10
const handled = new Set<string>(); // use your database in production
11

12
// express.text keeps the body as the exact text Scalekit signed
13
app.post('/scalekit/triggers', express.text({ type: 'application/json' }), (req, res) => {
14
  const body: string = req.body;
15
  try {
16
    scalekit.verifyWebhookPayload(
17
      process.env.SCALEKIT_TRIGGER_SECRET!,
18
      req.headers as Record<string, string>,
19
      body,
20
    );
21
  } catch (err) {
22
    if (!(err instanceof WebhookVerificationError)) throw err;
23
    // A bad or missing signature, or a request older than five minutes
24
    return res.sendStatus(400);
25
  }
26
  const event = JSON.parse(body);
27

28
  // Retries repeat an event. Key on dedupe_key plus the account you act as.
29
  const key = `${event.dedupe_key}:${event.connected_account_id}`;
30
  if (handled.has(key)) return res.sendStatus(204);
31

32
  if (event.delivery_scope === 'account') {
33
    console.log(`${event.trigger_type} for ${event.connected_account_id}: ${event.resource_id}`);
34
  } else {
35
    // A connection-wide event names no account: your app decides who acts on it
36
    console.log(`${event.trigger_type} on ${event.connection_id}: ${event.resource_id}`);
37
  }
38
  // Start your agent in a background job here, then respond
39

40
  handled.add(key);
41
  res.sendStatus(204);
42
});
43

44
app.listen(3000);

1
import base64
2
import hashlib
3
import hmac
4
import time
5

6

7
def verify_signature(body: bytes, headers: dict, secret: str) -> bool:
8
    """headers: the request headers, with lowercase names."""
9
    msg_id = headers.get("webhook-id")
10
    timestamp = headers.get("webhook-timestamp")
11
    signatures = headers.get("webhook-signature")
12
    if not (msg_id and timestamp and signatures and timestamp.isdigit()):
13
        return False
14
    if abs(time.time() - int(timestamp)) > 5 * 60:
15
        return False
16

17
    key = base64.b64decode(secret.removeprefix("whsec_"))
18
    signed = f"{msg_id}.{timestamp}.".encode() + body
19
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
20
    for candidate in signatures.split(" "):
21
        version, _, signature = candidate.partition(",")
22
        if version == "v1" and hmac.compare_digest(signature, expected):
23
            return True
24
    return False

The signature covers the body byte for byte. Verify the raw body exactly as received: parsing the JSON first and serializing it again changes the bytes and fails verification.

• Return a 2xx status fast. Start the agent’s work after you respond or in a background job. A response other than 2xx, or no response within 30 seconds, counts as a failure and is retried.
• Verify before you queue. Verify the signature in the handler that receives the request, then queue the verified event. A queued request can be older than five minutes by the time a worker reads it, and the SDK rejects it.
• Expect the same event more than once. Delivery is at least once. Scalekit sends an event again when it doesn’t get a 2xx from your endpoint within 30 seconds, including when your server handled the event but its response was slow or didn’t arrive. Each repeat carries the same dedupe_key. Store the keys you’ve handled and skip a repeat. When one connection-wide event makes several of your users act, store the key together with each user’s account, so a retry after a partial failure skips only the ones that finished.
• Don’t rely on order. Events can arrive out of order. Use occurred_at when order matters.

Scalekit makes up to 8 attempts to deliver an event, with increasing delays between them. Any status outside 2xx is a failure, including 4xx, and each attempt waits up to 30 seconds for a response.

If the eighth attempt fails, about 27 hours after the first, the delivery is marked as failed. Each attempt and your server’s response code appear under Recent delivery attempts on Developers > Trigger Delivery.

Every event has the same shape, for webhook and polling triggers alike. This event came from a Salesforce Lead created subscription:

1
{
2
  "version": "1",
3
  "trigger_type": "salesforce_lead_created",
4
  "subscription_id": "trgs_141020933185734981",
5
  "delivery_scope": "account",
6
  "connection_id": "conn_133400101014995480",
7
  "connected_account_id": "ca_133400349586228019",
8
  "resource_type": "salesforce_lead_created",
9
  "resource_id": "00Q5g00000AbCdEFGH",
10
  "occurred_at": "2026-10-10T09:14:03Z",
11
  "detection_mode": "poll",
12
  "payload_state": "full",
13
  "payload": {
14
    "attributes": {
15
      "type": "Lead",
16
      "url": "/services/data/v66.0/sobjects/Lead/00Q5g00000AbCdEFGH"
17
    },
18
    "Id": "00Q5g00000AbCdEFGH",
19
    "Name": "Jane Doe",
20
    "FirstName": "Jane",
21
    "LastName": "Doe",
22
    "Email": "jane@example.com",
23
    "Phone": null,
24
    "Company": "Example Corp",
25
    "Title": "VP Sales",
26
    "Status": "Open - Not Contacted",
27
    "LeadSource": "Web",
28
    "OwnerId": "0055g00000XyZabCDE",
29
    "CreatedDate": "2026-10-10T09:14:03.000+0000"
30
  },
31
  "dedupe_key": "ca_5F133400349586228019.trgs_5F141020933185734981.00Q5g00000AbCdEFGH",
32
  "correlation_id": "ca_5F133400349586228019.trgs_5F141020933185734981.00Q5g00000AbCdEFGH"
33
}

These fields are the same for every trigger. Only payload differs: it holds the app’s own data, so its fields depend on the trigger. For a polling trigger it’s the record, as above. For a webhook trigger it’s the request body the provider sent. Each connector’s page describes what its triggers send, as in Slack triggers.

The fields keep these snake_case names in every language. occurred_at is an RFC 3339 string in UTC.

• Treat dedupe_key and correlation_id as opaque strings. Compare them; don’t parse them. Their format can change.
• Expect new fields and values. Later versions can add fields and new values for delivery_scope, detection_mode and payload_state. Ignore fields you don’t know, and keep a default branch for unknown values.
• Read payload with the app’s field names. It’s the app’s own data, not a Scalekit format, so its shape differs per connector and trigger.

Make a change the trigger watches for, as in Set up a trigger. Your server prints a line such as salesforce_lead_created for ca_133400349586228019: 00Q5g00000AbCdEFGH, and Recent delivery attempts on Developers > Trigger Delivery shows the attempt with status 204.

The webhook-id, webhook-timestamp and webhook-signature headers didn’t reach the SDK. Check that a proxy in front of your server doesn’t strip them, and pass the request’s headers object unchanged.

Node.js spells it Invalid Signature. The body you verified isn’t byte for byte what Scalekit sent, or the secret belongs to another endpoint or environment. Verify the raw body before any JSON parsing, and copy the secret again with Reveal on Developers > Trigger Delivery.

The request is more than five minutes old, or your server’s clock is off. Sync the clock, and verify requests before you queue them.

A retry or a second delivery repeated the event. Skip events whose dedupe_key, together with the account you act as, you’ve already handled.