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

# Events

> Enable Soundcheck to emit CheckStatusChange and CertificationChange events to the Backstage events plugin for downstream automation.

Soundcheck can emit events to the [backstage events plugin](https://github.com/backstage/backstage/tree/master/plugins/events-node).

## Configuration

To enable events add the following configuration to your soundcheck config:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
soundcheck:
  events:
    enabled: true
```

Make sure you are also running the most recent version of `@spotify/backstage-plugin-soundcheck-node`, as this package includes typing for the events.

## Event Types

There are currently two types of events supported, `CheckStatusChangeEvent` and `CertificationChangeEvent`.

### CheckStatusChangeEvent

This event is emitted when a check status changes, for example if a check status goes from `failed` to `passed`.

Example Payload:

```js theme={"theme":{"light":"github-light","dark":"dracula"}}
eventPayload: {
  checkId: 'check-1',
  entityRef: 'component:default/test-1',
  state: 'passed',
  timestampMs: 1743777961,
  previousState: 'failed',
  scope: 'default'
},
topic: 'soundcheck-check-status-change',
```

If there was no prior check status, the event's `previousState` field will be `undefined`.

To use this event you can subscribe to it via events service:

```js theme={"theme":{"light":"github-light","dark":"dracula"}}
import { EventsService } from '@backstage/plugin-events-node';
import {
  CHECK_STATUS_CHANGE_TOPIC,
  CheckStatusChangeEvent,
} from '@spotify/backstage-plugin-soundcheck-node';

const subscribeToEvents = (events: EventsService) => {
  events.subscribe({
    id: 'test-sub',
    topics: [CHECK_STATUS_CHANGE_TOPIC],
    onEvent: async params => {
      // handle event
    },
  });
}
//...
subscribeToEvents(eventsService);
```

### CertificationStatusChangeEvent

This event is emitted when a certification state changes, for example if a certification for a level goes from `failed` to `passed`.

Example Payload:

```js theme={"theme":{"light":"github-light","dark":"dracula"}}
eventPayload: {
  trackId: 'track-1',
  entityRef: 'component:default/test-1',
  state: 'passed',
  cumulativeState: 'passed',
  levelOrdinal: 1,
  timestampMs: 1743777961,
  previousState: 'failed',
  scope: 'default',
},
topic: 'soundcheck-certification-change',
```

If there was no prior certification status, the event's `previousState` field will be `undefined`.

To use this event you can subscribe to it via events service:

```js theme={"theme":{"light":"github-light","dark":"dracula"}}
import { EventsService } from '@backstage/plugin-events-node';
import {
  CERTIFICATION_CHANGE_TOPIC,
  CertificationChangeEvent,
} from '@spotify/backstage-plugin-soundcheck-node';

const subscribeToEvents = (events: EventsService) => {
  events.subscribe({
    id: 'test-sub',
    topics: [CERTIFICATION_CHANGE_TOPIC],
    onEvent: async params => {
      // handle event
    },
  });
}
//...
subscribeToEvents(eventsService);
```