Implementing Events

Events let your connector turn a provider’s webhooks into normalized StackOne events. As a connector author, you declare the events in the connector YAML; StackOne handles subscription, signature verification, and delivery to a webhook. This is the producing side. For how a consumer subscribes and receives events, see Webhook Events; for the concept, see Events.

Where events live

Define event actions in a dedicated partial — {provider}.events.s1.partial.yaml — and reference it from the connector’s events block (separate from the top-level actions):

# {provider}.connector.s1.yaml
events:
  guides:
    setup:
      warning: "You need Admin privileges to create and manage webhooks."
      sections:
        - title: Copy the Native Webhook URL   # provider-specific steps shown when linking an account
          content: |
            ...
  actions:
    - $ref: provider.events   # the event-action partial

Anatomy of an event

Each event is an action with actionType: event. It names the provider’s native events, maps the incoming webhook payload to its inputs, and emits a normalized event with the emit_event step function:

# {provider}.events.s1.partial.yaml
- actionId: webhook_employee_created
  categories:
    - hris
  actionType: event
  label: Employee Created
  description: Processes employee.created events fired when a new employee is added.
  providerEvents:
    - employee.created          # the provider's native event name(s)
  inputs:                       # shape of the incoming webhook payload
    - name: type
      type: string
      in: body
    - name: triggeredAt
      type: string
      in: body
    - name: data
      type: object
      in: body
      properties:
        - name: employeeId
          type: string
  steps:
    - stepId: emit
      description: Emit the normalized event to the StackOne dispatcher.
      stepFunction:
        functionName: emit_event
        parameters:
          event:
            eventId: $.inputs.data.employeeId
            eventType: $.inputs.type
            eventDate: $.inputs.triggeredAt
            data: $.inputs.data
  result:
    statusCode: 200             # acknowledge receipt to the provider
    body:
      status: OK

Field	Purpose
`actionType: event`	Marks the action as an inbound event handler, not an API call.
`providerEvents`	The provider’s native event names this handler accepts.
`inputs`	The fields of the incoming webhook payload.
`emit_event` step	Maps the payload to a normalized event (`eventId`, `eventType`, `eventDate`, `data`).
`result`	The `200` acknowledgement returned to the provider.

Native Webhook URL

When a provider is configured manually, expose a Native Webhook URL on the connector profile by adding a field to your authentication config:

- key: nativeWebhookUrl
  label: Native Webhook URL
  value: "{{webhookEventsUrl(webhooks_url, orgId, projectSecureId, connectorProfileId, external_trigger_token)}}"
  description: Paste this into the provider's webhook settings.

The user copies this URL into the provider’s own webhook configuration, guided by the steps you define in events.guides.setup. For every field, see the YAML Schema.

​Where events live

​Anatomy of an event

​Native Webhook URL

Where events live

Anatomy of an event

Native Webhook URL