SCscalekit
Triggers

Subscribe to a trigger

Changed on

Creates a subscription to one trigger, either for one connected account or for the whole connection. Use this endpoint after ListAvailableTriggers and ListEligibleAccounts have shown that the trigger and account can be used. Pass the connection ID in the path, and trigger_name in the body. For an account-scoped trigger, pass connected_account_id; for a connection-scoped trigger, omit it. Use config to set the trigger's filter values, with keys spelled exactly as the trigger's config_fields declare them. For a polled trigger, interval_seconds sets the polling interval, and defaults to the trigger's default interval. An interval below the trigger's minimum is refused, not rounded up. Each refusal says what to change, for example the missing scope, the minimum interval, or that the account was authorized under a different app. Returns the new subscription with its status, its requested and effective intervals, and the account's health for this trigger.

post/api/v1/connections/{connection_id}/trigger-subscriptions

Request

Path parameters

connection_idstring required

ID of the connection, in this environment. Up to 64 characters.

Request body

configobject

Filter values for the subscription, keyed by the trigger's config_fields keys, spelled exactly as returned. Every required field must be set. An unknown key, or a value longer than 512 characters, is refused. Subscribing again with different values creates another subscription; subscribing again with identical values returns 409.

connected_account_idstring

Connected account to subscribe on, for an account-scoped trigger. Omit it for a connection-scoped trigger — the trigger is then subscribed on the connection itself and no account is named. Whether omitting it is valid depends on the trigger's own delivery_scope.

interval_secondsinteger

Polling interval in seconds, for a polled trigger only. Omit it to use the trigger's default_interval_seconds. A value below the trigger's min_interval_seconds is refused, naming the minimum, rather than rounded up. Setting it for a webhook trigger is refused. The subscription can run slower than requested when the environment's polling budget is shared across many polled subscriptions; effective_interval_seconds on the response shows the interval it runs at.

trigger_namestring required

Name of the trigger to subscribe to, as returned in the name field of ListAvailableTriggers. Up to 128 characters.

Example request

{
  "config": {
    "channel": "C0123456789"
  },
  "connected_account_id": "ca_123456789012345",
  "interval_seconds": 300,
  "trigger_name": "slack_message_posted"
}

Response

The created subscription, including its status, intervals, filter values and the subscribed account's health

account_health'READY' | 'AWAITING_CONFIRMATION' | 'WRONG_APP' | 'DISCONNECTED' | 'NEEDS_REAUTHENTICATION'

A connected account's own state, evaluated for what the trigger in question routes by: a webhook trigger needs the provider workspace captured, and an account-scoped webhook trigger the provider user too.

  • READY: The account can receive triggers.
  • AWAITING_CONFIRMATION: Connected and working, but Scalekit has not confirmed which provider workspace or user it belongs to, so inbound events cannot be routed to it.
  • WRONG_APP: Authorized under a different OAuth app than the connection now uses.
  • DISCONNECTED: The account was disconnected.
  • NEEDS_REAUTHENTICATION: The credential itself is unusable: it has expired, or the account has not finished connecting.
configobject

The subscription's filter values, keyed by the trigger's config_fields keys. Keys are returned exactly as stored; send them back without changing their case.

connected_account_idstring

ID of the subscribed connected account. Empty for a connection-scoped subscription.

connected_account_identifierstring

The identifier the connected account was created with, such as your app's user ID or the user's email address, so a client can label the subscription without fetching every account separately. Empty for a connection-scoped subscription, and empty when the account has no identifier recorded — fall back to connected_account_id rather than showing a blank.

connection_idstring

ID of the connection the subscription belongs to.

created_atstring date-time

When the subscription was created. Returned so a list can be ordered or explained by age without a second lookup.

delivery_scope'ACCOUNT' | 'CONNECTION'

Whether a trigger delivers once per connected account or once for the whole connection.

Set by the trigger, not chosen by the subscriber. A polled trigger polls with one connected account's credential, so a polled trigger that is connection-scoped is reported as unavailable.

  • ACCOUNT: One event per subscribed connected account. For a webhook trigger, an event is delivered for an account only when the event's provider workspace and user match the account's; a polled trigger polls each account with that account's own credential. Subscribed on a specific connected account.
  • CONNECTION: One event for the whole connection, whatever accounts exist on it. Subscribed on the connection itself, naming no account.
effective_interval_secondsinteger

The polling interval, in seconds, the subscription actually runs at. Larger than requested_interval_seconds when the environment's polling budget is shared across many polled subscriptions; the subscription's status is then THROTTLED. Zero for a webhook trigger.

idstring

Unique identifier of the trigger subscription.

providerstring

The provider the trigger belongs to.

requested_interval_secondsinteger

The polling interval, in seconds, the subscription asked for, or the trigger's default when it did not set one. Returned next to effective_interval_seconds so a subscription running slower than requested is visible. Zero for a webhook trigger.

status'ACTIVE' | 'THROTTLED' | 'PAUSED' | 'PAUSED_CREDENTIAL'

Why a subscription is or is not currently delivering.

  • ACTIVE: Delivering. For a polled trigger, at the requested interval.
  • THROTTLED: Running slower than requested, not stopped. Still delivering.
  • PAUSED: Stopped by the customer.
  • PAUSED_CREDENTIAL: Stopped because the account's credential no longer works. Distinct from PAUSED so the two have distinguishable explanations for missing events.
trigger_namestring

Name of the subscribed trigger, as returned by ListAvailableTriggers.

Example response

{
  "config": {
    "channel": "C0123456789"
  },
  "connected_account_id": "ca_123456789012345",
  "connected_account_identifier": "user_123",
  "connection_id": "conn_123456789012345",
  "effective_interval_seconds": 60,
  "id": "trgs_123456789012345",
  "poll_state": {
    "last_error": "The provider is rate-limiting requests. Polling resumes automatically after a backoff."
  },
  "provider": "slack",
  "requested_interval_seconds": 60,
  "trigger_name": "slack_message_posted"
}

Changes