Skip to content

Player webhooks

Mestra Player webhooks

Mestra Player sends the same kind of webhook event as the rest of Mestra. This page lists the events that are particular to Mestra Player screens. Every event has the shape described there, and is signed, retried and tested the same way. Add an endpoint and choose these events as you would any other: see 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.

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 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 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). 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.

  • 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. 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/…"
}
}
}