> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Implementing Events

> Define the events your connector emits in its YAML, so StackOne can normalize and deliver them.

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](/connect/webhooks).

This is the **producing** side. For how a consumer subscribes and receives events, see [Webhook Events](/connect/webhooks); for the concept, see [Events](/gateway/concepts/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`):

```yaml theme={null}
# {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:

```yaml theme={null}
# {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:

```yaml theme={null}
- 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](/connector-yaml-reference/yaml-schema).