# Mestra Player webhooks

The webhook events Mestra Player sends: screens going online and offline, problems, command results, takedowns, install keys and plays.

Mestra Player sends the same kind of [webhook event](https://withmestra.com/docs/webhooks/) as the rest of Mestra. This page lists the events that are particular to Mestra Player screens. Every event has the [shape](https://withmestra.com/docs/webhooks/events/) described there, and is [signed](https://withmestra.com/docs/webhooks/signatures/), [retried](https://withmestra.com/docs/webhooks/retries/) and [tested](https://withmestra.com/docs/webhooks/testing/) the same way. Add an endpoint and choose these events as you would any other: see [Endpoints](https://withmestra.com/docs/webhooks/endpoints/).

An event says what happened and where to look. It carries ids and a few plain values, never artwork, screenshots, logs or file names. Fetch the rest with the [Mestra Player API](https://withmestra.com/docs/player/api/).

New event types are added over time. Ignore types you don't know.

## The events

| Type                    | Fires when                                                                                                                                                | Object   |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `screen.online`         | A Mestra screen calls in after being offline                                                                                                              | screen   |
| `screen.offline`        | A Mestra screen has not called in for 3 minutes                                                                                                           | screen   |
| `screen.file_mismatch`  | A Mestra screen found a cached file that failed its check and fetched it again                                                                            | screen   |
| `screen.issue`          | A Mestra screen has a problem it could not fix by itself, or one that needs a person                                                                      | screen   |
| `screen.recovered`      | A Mestra screen's problem is fixed                                                                                                                        | screen   |
| `screen.update_waiting` | A security update for a Mestra screen is waiting: updates are paused, or the screen has no time set to apply it                                           | screen   |
| `screen.action_done`    | A remote action on a Mestra screen finished, failed or expired                                                                                            | screen   |
| `takedown.done`         | No screen of a takedown is still waiting to go off: each reported the content off, was removed, or was started again                                      | takedown |
| `screen.enrolled`       | One or more Mestra screens join with an install key                                                                                                       | none     |
| `install_key.alert`     | An install key passes its expected screens, a revoked or expired key is tried, enrolments with it come too fast, or a screen reports its key was readable | none     |
| `plays.received`        | A Mestra screen's plays arrive (about once a minute per playing screen). Sent only to endpoints that ask for it by name                                   | screen   |

`plays.received` is opt-in. Every other type here goes to an endpoint that subscribes to it, or to all events.

## Objects

Events about a screen point at it in `data.object`, and `takedown.done` points at the takedown. The `type` of the object is `screen` or `takedown`, and `url` is where to fetch it from the API.

| Object   | URL                             |
| -------- | ------------------------------- |
| Screen   | `/api/v1/player/devices/{id}`   |
| Takedown | `/api/v1/player/takedowns/{id}` |

`screen.enrolled` and `install_key.alert` have no object. Their details are in `data`.

The events also carry plain values in `data`, such as `screenId`. They are described below.

## Read these events from the API

[`GET /api/v1/events`](https://withmestra.com/docs/webhooks/testing/#list-events-from-the-api) lists events for catching up after downtime. For the Mestra Player events:

- The key needs **Screens · Read**, and the person or service behind it must be an owner.
- A key limited to some screens sees only the events that name its screens. It doesn't see `screen.enrolled`, `install_key.alert` or `takedown.done`. It reads takedowns from the [takedown routes](https://withmestra.com/docs/api/stop-and-takedowns/#listmestratakedowns) instead.
- `plays.received` is listed only when you ask for it with `type=plays.received`.

An endpoint itself gets every event it subscribes to. The limits above apply to reading events through the API, not to delivery.

## `screen.online`

A Mestra screen calls in after being offline. `screenId` is the screen's id and `site` the key of the centre it is linked to, or null. `offlineSeconds` is how long the screen had been silent, or null the first time it ever calls in. When the screen is a member of a screen group, `data.group` holds the group's `id` and the screen's `position`.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.online",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "site": "north-mall",
    "offlineSeconds": 640,
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```

## `screen.offline`

A Mestra screen has not called in for 3 minutes. `screenId` is the screen's id and `site` the key of the centre it is linked to, or null. `lastSeenAt` is when the screen last called in. It is found by a check that runs every minute, so it can arrive up to a minute after the 3 minutes. When the screen is a member of a screen group, `data.group` holds the group's `id` and the screen's `position`.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.offline",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "site": "north-mall",
    "lastSeenAt": "2026-10-22T03:11:09Z",
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```

## `screen.file_mismatch`

A Mestra screen found a cached file that failed its check and fetched it again. `screenId` is the screen's id and `site` the key of the centre it is linked to, or null. `entryId` is the id of the entry whose cached file failed its check (`stopshow` for the stop picture). It is sent at most once a day (UTC) for each file of a screen, one event for each file.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.file_mismatch",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "site": null,
    "entryId": "…",
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```

## `screen.issue`

A Mestra screen has a problem it could not fix by itself, or one that needs a person. `screenId` is the screen's id and `site` the key of the centre it is linked to, or null. `code` names the problem, `severity` is `info`, `warn` or `down`, `title` says what is wrong and `fix` what to do, in the words the screen's page shows. `openedAt` is when it began and `selfHealed` says whether a step the screen took fixed it. It is sent once for each problem that stays open for a while (one the screen keeps trying to fix by itself included), or at once when the PC needs a visit or many of your screens have the same problem. A problem the screen fixes by itself soon after sends nothing, unless it keeps coming back. Then it is sent once that day, with `closedAt` set when the problem is not open at that moment.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.issue",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "site": "north-mall",
    "code": "net_dns",
    "severity": "warn",
    "title": "The PC can't look up Mestra's address",
    "fix": "The site's network is blocking address lookups. Ask the site to check its DNS settings.",
    "openedAt": "2026-10-22T03:11:09Z",
    "selfHealed": false,
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```

## `screen.recovered`

A Mestra screen's problem is fixed. The same data as `screen.issue`, plus `closedAt`, when the problem ended, and `selfHealed`, true when the screen fixed it. It is sent once, and only for a problem that was sent as `screen.issue`.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.recovered",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "site": "north-mall",
    "code": "net_dns",
    "severity": "warn",
    "title": "The PC can't look up Mestra's address",
    "fix": "The site's network is blocking address lookups. Ask the site to check its DNS settings.",
    "openedAt": "2026-10-22T03:11:09Z",
    "selfHealed": false,
    "closedAt": "2026-10-22T03:40:02Z",
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```

## `screen.update_waiting`

A security update for a Mestra screen is waiting: updates are paused, or the screen has no time set to apply it. `screenId` is the screen's id and `seq` the number of the security update it is waiting for. It is sent once for each screen and update. Choose a time for the screen, or apply the update now, in Mestra.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.update_waiting",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "seq": 12,
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```

## `screen.action_done`

A remote action on a Mestra screen finished, failed or expired. `screenId` is the screen's id and `commandId` the command (see [Screen commands](https://withmestra.com/docs/api/screen-commands/#getmestrascreencommand)). `action` is `shot`, `logs`, `restart`, `refetch` or `reboot`. `status` is `done`, `failed` or `expired`: the screen did it, the screen said it could not, or it never took the command in time. `captureId` is the screenshot or log bundle the action made, or null. There is one event for each command, for its first outcome only.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.action_done",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "commandId": "…",
    "action": "shot",
    "status": "done",
    "captureId": "…",
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```

## `takedown.done`

No screen of a takedown is still waiting to go off: each reported the content off, was removed, or was started again. `takedownId` is the takedown's id and `scope` is `publication`, `screen`, `site` or `all`. It fires once, when no target screen is still pending or told. `screens` lists each target screen's `id` and its outcome `state`: `off` (the screen's own heartbeat reported the content off), `removed` (the screen was deleted first) or `started_again` (someone started the screen again first, so the content may be back on). `counts` has the number of screens with each outcome (`off`, `removed`, `startedAgain`). See [Stop and takedowns](https://withmestra.com/docs/api/stop-and-takedowns/#createmestratakedown).

- **Object:** takedown, at `/api/v1/player/takedowns/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "takedown.done",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "takedownId": "…",
    "scope": "publication",
    "screens": [
      {
        "id": "…",
        "state": "off"
      },
      {
        "id": "…",
        "state": "started_again"
      }
    ],
    "counts": {
      "off": 1,
      "removed": 0,
      "startedAgain": 1
    },
    "object": {
      "id": "…",
      "type": "takedown",
      "url": "https://app.withmestra.com/api/v1/player/takedowns/…"
    }
  }
}
```

## `screen.enrolled`

One or more Mestra screens join with an install key. `installKeyId` is the install key the screens joined with, `screens` how many joined with it in the period the event covers, and `firstScreenId` the first of them. A rollout that enrols many screens at once is one event for each key, sent when the period ends, not one event for each screen. List the key's unassigned screens through the API for the rest. It carries ids and a count only: neither the key's name nor its value is sent.

- **Object:** none. The details are in `data`.

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "screen.enrolled",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "installKeyId": "…",
    "screens": 12,
    "firstScreenId": "…"
  }
}
```

## `install_key.alert`

An install key passes its expected screens, a revoked or expired key is tried, enrolments with it come too fast, or a screen reports its key was readable. `installKeyId` is the install key's id. `reason` is `expected_passed` (more screens joined with the key than its owner expected; sent once, and again only after the expected number is raised and passed again), `refused` (a revoked or expired key was tried), `capped` (screens tried to join with the key faster than Mestra allows, so some were refused; a leaked key enrolling rogue screens looks like this) or `exposed` (a screen set up from a provisioning package found a readable copy of the key on its PC and refused to use it; the key still works until revoked). `refused`, `capped` and `exposed` are each sent at most once in a while for each key. `devices` is how many screens joined with the key, `expected` the number its owner expected or null, and `refused` how many times it was tried after it stopped working. It carries ids and counts only, never the key's name or value.

- **Object:** none. The details are in `data`.

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "install_key.alert",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "installKeyId": "…",
    "reason": "expected_passed",
    "devices": 41,
    "expected": 40,
    "refused": 0
  }
}
```

## `plays.received`

A Mestra screen's plays arrive (about once a minute per playing screen). Sent only to endpoints that ask for it by name. This event is opt-in. An endpoint that takes all events does not get it, and `GET /api/v1/events` returns it only when asked for with `type=plays.received`. It is stored only while an enabled endpoint names it, so that list has nothing from before the first such endpoint. There is one event for each batch of plays a screen uploads, which a screen does about once a minute while it is playing. `screenId` is the screen's id, `batchId` the batch (the id of its signed receipt), `plays` how many plays are new in it, `playedFrom` and `playedTo` the earliest and latest play start on the screen's own clock, and `readableAt` the time from which the plays can be read from the [plays routes](https://withmestra.com/docs/api/plays/). It carries no names.

- **Object:** screen, at `/api/v1/player/devices/{id}`

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "plays.received",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "screenId": "…",
    "batchId": "…",
    "plays": 12,
    "playedFrom": "2026-10-22T09:00:00.000",
    "playedTo": "2026-10-22T09:01:50.000",
    "readableAt": "2026-10-22T03:15:16.000000Z",
    "object": {
      "id": "…",
      "type": "screen",
      "url": "https://app.withmestra.com/api/v1/player/devices/…"
    }
  }
}
```
