Events - Stackone

Configures a connector’s inbound webhooks. For how event handling works end to end, see Implementing events.

overview

Event and webhook configuration for the connector.

Field	Description	Type	Required
`actions`	Event actions that process incoming provider events.	object[]	No
`externalAccountIdExtractor`	Action that reads the provider’s external account identifier from an incoming payload so the event can be matched to a linked account.	object	No
`guides`	Manual webhook setup guides.	object	No
`router`	Rules mapping incoming payloads to event actions.	object	No
`setup`	Programmatic webhook lifecycle configuration.	object	No

Examples

events:
  setup:
    creation:
      steps:
        - stepId: create_webhook
          description: Register a webhook receiver.
          stepFunction:
            functionName: request
            version: v1
            parameters:
              url: /webhooks
              method: post
              args:
                - name: url
                  value: '${inputs.callbackUrl}'
                  in: body
      result: '$.id'
    deletion:
      steps:
        - stepId: delete_webhook
          description: Remove the webhook receiver.
          stepFunction:
            functionName: request
            version: v1
            parameters:
              url: '/webhooks/${inputs.remoteId}'
              method: delete
  router:
    rules:
      - when: '${event.type == "user.created"}'
        then: { action: user_created_event }

actions

Event actions that process incoming provider events. Same fields as actions, plus:

Field	Description	Type	Required
`requiresManualSetup`	Whether the webhook must be configured manually in the provider UI.	boolean	No

Examples

events:
  actions:
    - actionId: handle_ticket_created
      actionType: event
      label: Ticket created webhook
      description: Processes ticket.created events from the provider.
      providerEvents: [ticket.created]
      inputs:
        - name: event
          description: The provider event object from the delivery.
          type: object
          in: body
          required: false
      steps:
        - stepId: emit
          description: Emit the ticket.created event to StackOne's dispatcher.
          stepFunction:
            functionName: emit_event
            parameters:
              event:
                eventType: ticket.created
                eventId: $.inputs.event.id
                data: $.inputs.event
      result:
        statusCode: 200
        body:
          status: OK

externalAccountIdExtractor

Action that reads the provider’s external account identifier from an incoming payload so the event can be matched to a linked account. Same fields as actions. Examples

events:
  externalAccountIdExtractor:
    actionId: extract_account_id
    actionType: custom
    label: Extract account ID from event
    description: Map provider tenant ID to StackOne linked account.
    steps:
      - stepId: lookup
        stepFunction:
          functionName: request
          version: v1
          parameters:
            url: 'https://internal/accounts/by-tenant/${inputs.tenant_id}'
            method: get
    result: '${steps.lookup.output.data.linked_account_id}'

guides

Manual webhook setup guides.

Field	Description	Type	Required
`setup`	Guide for configuring webhooks in the provider UI.	object	No

guides.setup

Guide for configuring webhooks in the provider UI.

Field	Description	Type	Required
`sections`	Ordered sections making up the guide.	object[]	Yes
`warning`	Cautionary note shown at the top of the guide.	string	No

guides.setup.sections

Ordered sections making up the guide.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this section is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Introductory text for the section.	string	Yes
`image`	Illustrative image for the section.	object	No
`list`	Ordered items elaborating the section.	string[]	No
`steps`	Ordered steps making up the section.	object[]	No
`title`	Heading for this guide section.	string	Yes

guides.setup.sections.image

Illustrative image for the section.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

guides.setup.sections.steps

Ordered steps making up the section.

Field	Description	Type	Required
`applicableScopes`	Scope names for which this step is shown. Space-separated, with any name that contains spaces wrapped in double quotes.	string	No
`content`	Body text describing what the user should do.	string	Yes
`displayScopes`	Whether the step shows badges for the actions its scopes unlock.	boolean	No
`image`	Illustrative image for the step.	object	No
`list`	Ordered items elaborating the step.	string[]	No
`title`	Heading for this guide step.	string	Yes

guides.setup.sections.steps.image

Illustrative image for the step.

Field	Description	Type	Required
`alt`	Alternative text describing the image.	string	Yes
`src`	Image URL or a path relative to the connector.	string	Yes

Examples

guides:
  setup:
    sections:
      - title: Enable webhooks
        content: Turn on event delivery in the provider dashboard.
        steps:
          - title: Open webhook settings
            content: Go to Settings, then Webhooks.

router

Rules mapping incoming payloads to event actions.

Field	Description	Type	Required
`delivery`	Rules matched against the whole delivery payload, rather than the individual events `itemsPath` splits it into. The first match short-circuits, so the per-event `rules` are skipped.	object[]	No
`itemsPath`	Expression that splits a batched delivery payload into individual events, so each is routed on its own through `rules`. When omitted, the whole payload is treated as a single event.	string	No
`rules`	Rules matched in order against each individual event, where the first match maps it to an event action. Skipped when a `delivery` rule matches.	object[]	Yes

router.delivery

Rules matched against the whole delivery payload, rather than the individual events itemsPath splits it into. The first match short-circuits, so the per-event rules are skipped.

Field	Description	Type	Required
`then`	Action to invoke when the rule matches.	object	Yes
`when`	Expression evaluated against the incoming request. This rule is selected when the expression returns anything other than null, false, or undefined.	string	Yes

router.delivery.then

Action to invoke when the rule matches.

Field	Description	Type	Required
`action`	Event action id invoked when the rule matches.	string	Yes
`input`	Expressions evaluated against the incoming request whose results become the invoked action’s input.	object	No

router.rules

Rules matched in order against each individual event, where the first match maps it to an event action. Skipped when a delivery rule matches.

Field	Description	Type	Required
`then`	Action to invoke when the rule matches.	object	Yes
`when`	Expression evaluated against the incoming request. This rule is selected when the expression returns anything other than null, false, or undefined.	string	Yes

router.rules.then

Action to invoke when the rule matches.

Field	Description	Type	Required
`action`	Event action id invoked when the rule matches.	string	Yes
`input`	Expressions evaluated against the incoming request whose results become the invoked action’s input.	object	No

Examples

events:
  router:
    rules:
      - when: '${event.type == "user.created"}'
        then: { action: handle_user_created }

      - when: '${event.type == "user.updated" && event.changes.contains("email")}'
        then:
          action: handle_email_change
          input:
            user_id: '${event.data.id}'
            new_email: '${event.data.email}'

setup

Programmatic webhook lifecycle configuration.

Field	Description	Type	Required
`activation`	Optional phase that activates the receiver after creation.	object	No
`creation`	Phase that registers the webhook receiver.	object	Yes
`deletion`	Phase that removes the webhook receiver.	object	Yes
`isConsolidated`	Whether one receiver handles all events rather than one per event. Default: `false`	boolean	Yes

setup.activation

Optional phase that activates the receiver after creation.

Field	Description	Type	Required
`result`	Value produced by the phase, such as the created webhook id.	string	No
`steps`	Ordered steps performed in this webhook phase.	array	Yes

setup.creation

Phase that registers the webhook receiver.

Field	Description	Type	Required
`result`	Expression selecting the value this phase produces, such as the created receiver’s remote id (e.g. `$.steps.create.output.data.id`), which later phases reference as `${inputs.remoteId}`.	string	Yes
`steps`	Ordered steps performed in this webhook phase.	array	Yes

setup.deletion

Phase that removes the webhook receiver.

Field	Description	Type	Required
`result`	Value produced by the phase, such as the created webhook id.	string	No
`steps`	Ordered steps performed in this webhook phase.	array	Yes

Examples

events:
  setup:
    creation:
      steps:
        - stepId: create_webhook
          description: Register a webhook receiver.
          stepFunction:
            functionName: request
            version: v1
            parameters:
              url: /webhooks
              method: post
              args:
                - { name: url, value: '${inputs.callbackUrl}', in: body }
                - { name: events, value: '${inputs.eventTypes}', in: body }
      result: '$.id'

    activation:
      steps:
        - stepId: activate
          description: Mark webhook active.
          stepFunction:
            functionName: request
            version: v1
            parameters:
              url: '/webhooks/${inputs.remoteId}/activate'
              method: post

    deletion:
      steps:
        - stepId: delete_webhook
          description: Remove the receiver.
          stepFunction:
            functionName: request
            version: v1
            parameters:
              url: '/webhooks/${inputs.remoteId}'
              method: delete

    isConsolidated: false

Actions overview

The full action shape event actions and the extractor are built from.

Step functions: emit_event

Fan out events to downstream subscribers.

Expression language

JEXL syntax for the router’s when rules.

Action steps

The step shape each setup phase reuses.

​overview

​actions

​externalAccountIdExtractor

​guides

​router

​setup

​Related

Actions overview

Step functions: emit_event

Expression language

Action steps

overview

actions

externalAccountIdExtractor

guides

router

setup

Related