# Emit WebSocket Event API

> Push a notification to the WebSocket clients subscribed to a custom event of API Maker with the emit event WS system API, from any server or any code.

Source: https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-emit-event-ws-api.html

Sends the data to every client subscribed to a custom [WebSocket event](https://docs.apimaker.dev/v1/docs/pages/web-socket-event-page.html) whose subscription condition matches, whatever server the client is connected to.

| | |
|---|---|
| Method | POST |
| URL | `/api/system-api/admin/emit-event-ws` : `admin` is the user path of your account |
| Body | `{ name, eventData? }` or an array of them |
| Answer | `data` : `true` |
| From code | [`g.sys.system.emitEventWS`](https://docs.apimaker.dev/v1/examples/sys/system/emitEventWS.html) |

## The call

**Body**

```json
{ "name": "default/orders-updated", "eventData": { "recipientId": "42", "order_no": 1001, "status": "SHIPPED" } }
```

**Body : several events**

```json
[
    { "name": "default/orders-updated", "eventData": { "recipientId": "42", "order_no": 1001 } },
    { "name": "stock-alerts", "eventData": { "sku": "WM-1", "qty": 2 } }
]
```

- The event must exist on the WebSocket Events page. A client receives the data when its subscription has no condition, or when the emitted data has the values of its `criteria`.
- To notify one person, put their id in the data and let their client subscribe with that id in `criteria`.

## From code

```typescript
await g.sys.system.emitEventWS('default/orders-updated', { recipientId: '42', order_no: 1001 });
```

## Access and settings

- Over HTTP, a system API answers once its [settings](https://docs.apimaker.dev/v1/docs/settings/systemApiSettings.html) give it `apiAccessType: TOKEN_ACCESS` (the token of an API user whose [group](https://docs.apimaker.dev/v1/docs/apis-security/api-group-permission.html) grants this system API, in `x-am-authorization`) or `IS_PUBLIC`. Without settings it is `NO_ACCESS` : your code calls it through `g.sys`, the admin panel tests it, and an HTTP call is refused. The group must also grant the WebSocket event.
- The settings can also cache the answer or require person tokens (`authProviders`) ; [pre and post hooks](https://docs.apimaker.dev/v1/docs/apis-all/hooks/preHook-api.html) run around it like around any API.
- The [request headers](https://docs.apimaker.dev/v1/docs/apis-all/header/requestHeader.html) apply : `x-am-response-case`, `x-am-content-type-response`, `x-am-internationalization`, `x-am-tenant-username`…

## Errors

| Code | When |
|---|---|
| `400` | The body is wrong : the message names the missing or invalid key, `WebSocket event not found with name …` for an unknown event. |
| `401` | No valid API user token, or the API is `NO_ACCESS` : `You are not authorized to access this API.` |
| `403` | No group grants this system API. |

## Related

- [All APIs at a glance](https://docs.apimaker.dev/v1/docs/apis-all/overview.html) · [Response format](https://docs.apimaker.dev/v1/docs/apis-all/response-format.html) · [System API settings](https://docs.apimaker.dev/v1/docs/settings/systemApiSettings.html) · [System APIs from code](https://docs.apimaker.dev/v1/examples/sys/system/system.html)