# Webiny Websocket Notifications

Sending real-time notifications from the API to the Admin app over websockets, and...

- Repository: https://github.com/webiny/webiny-js (8051 stars)
- Category: Design
- License: see repository
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add webiny/webiny-js --skill webiny-websocket-notifications -g -a claude-code -y`
Codex: `npx skills add webiny/webiny-js --skill webiny-websocket-notifications -g -a codex -y`
Cursor: `npx skills add webiny/webiny-js --skill webiny-websocket-notifications -g -a cursor -y`
Gemini CLI: `npx skills add webiny/webiny-js --skill webiny-websocket-notifications -g -a gemini-cli -y`

## Description

Sending real-time notifications from the API to the Admin app over websockets, and reacting to them on the client. Use this skill when the developer wants to push a message to the user who triggered some server-side work (e.g. per-entry progress from a background task/bulk action) and show a toast, update a cache, or refresh UI in response. Requires Webiny 6.5.0 or newer.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Websocket notifications (API → Admin)

## TL;DR

On the **API**, inject `WebsocketsSendToIdentityUseCase` (`webiny/api`) + `IdentityContext`
(`webiny/api/security`) and call `sendToIdentity.execute({ id }, { action, data })`. On the
**Admin**, implement a `WebsocketEventHandler` (`webiny/admin/websockets`) that filters on
`action` and reacts (e.g. toast via `Notifications` from `webiny/admin`), registered with
`createFeature` + `RegisterFeature`.

## API, emit

```typescript
import { WebsocketsSendToIdentityUseCase } from "webiny/api";
import { IdentityContext } from "webiny/api/security";

class MyTaskOrHook {
  constructor(
    private identityContext: IdentityContext.Interface,
    private sendToIdentity: WebsocketsSendToIdentityUseCase.Interface
  ) {}

  async notify(entry) {
    // Best-effort: a websocket failure must never fail the real work.
    try {
      const identity = this.identityContext.getIdentity();
      if (identity) {
        await this.sendToIdentity.execute(
          { id: identity.id },
          {
            action: "cms.product.discountApplied",
            data: { id: entry.entryId, price: entry.values.price }
          }
        );
      }
    } catch (ex) {
      // log & swallow
    }
  }
}
// dependencies: [IdentityContext, WebsocketsSendToIdentityUseCase]
```

- Send to the user who triggered the work, get them from `IdentityContext`. In a
  background task/bulk action, the triggering identity is available.
- Use a namespaced `action` string; put the payload in `data`.
- Sender data type: `{ action?: string; data?: T; error?: {...} }`.

## Admin, listen

```typescript
import { WebsocketEventHandler } from "webiny/admin/websockets";
import { Notifications } from "webiny/admin";

const ACTION = "cms.product.discountApplied";

class MyHandlerImpl implements WebsocketEventHandler.Interface {
  constructor(private notifications: Notifications.Interface) {}

The rest: https://github.com/webiny/webiny-js/blob/HEAD/skills/user-skills/api/websocket-notifications/SKILL.md