# Event types

Every Mestra webhook event type, when it fires, and what to fetch.

Every event has the same [shape](https://withmestra.com/docs/webhooks/events/). This page lists each type, when it fires, what to fetch and which API permission area can read it.

| Type                       | Fires when                                                                                                                                        | Object          | Area      |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | --------- |
| `run.completed`            | A run finishes                                                                                                                                    | run             | runs      |
| `run.failed`               | A run fails                                                                                                                                       | run             | runs      |
| `run.cancelled`            | A run is cancelled                                                                                                                                | run             | runs      |
| `master.saved`             | A master is saved or replaced                                                                                                                     | master          | runs      |
| `render.checked`           | An output of a run is checked: against its campaign's rules, or, with no rule set, by the checks that need none                                   | run             | runs      |
| `size.edited`              | A size is edited and saved in the editor or through the API                                                                                       | run sizes       | designs   |
| `review.round_sent`        | A review round goes out                                                                                                                           | review campaign | reviews   |
| `review.approved`          | A reviewer approves                                                                                                                               | review campaign | reviews   |
| `review.changes_requested` | A reviewer asks for changes                                                                                                                       | review campaign | reviews   |
| `comment.created`          | A review comment is added                                                                                                                         | review campaign | reviews   |
| `comment.resolved`         | A review comment is resolved                                                                                                                      | review campaign | reviews   |
| `export.ready`             | A review export is ready                                                                                                                          | export          | reviews   |
| `export.failed`            | A review export fails                                                                                                                             | export          | reviews   |
| `publish.finished`         | A publish to a screen network finishes, including a booking made in Mestra Player                                                                 | none            | campaigns |
| `dynamic.summary`          | Once a day for a campaign whose variants changed                                                                                                  | none            | campaigns |
| `booking.submitted`        | A customer submits artwork for a Network booking                                                                                                  | none            | campaigns |
| `booking.approved`         | Staff approve a Network booking                                                                                                                   | none            | campaigns |
| `booking.live`             | A Network booking is live on screens with every size live                                                                                         | none            | campaigns |
| `booking.partly_live`      | A Network booking is on screens with some sizes held back                                                                                         | none            | campaigns |
| `booking.taken_down`       | Staff take a Network booking down                                                                                                                 | none            | campaigns |
| `booking.held`             | Sizes of a Network booking were held back from screens                                                                                            | none            | campaigns |
| `screen.online`            | A Mestra screen calls in after being offline                                                                                                      | screen          | screens   |
| `screen.offline`           | A Mestra screen has not called in for 3 minutes                                                                                                   | screen          | screens   |
| `screen.file_mismatch`     | A Mestra screen found a cached file that failed its check and fetched it again                                                                    | screen          | screens   |
| `screen.enrolled`          | One or more Mestra screens join with an install key                                                                                               | none            | screens   |
| `screen.issue`             | A Mestra screen has a problem it could not fix by itself, or one that needs a person                                                              | screen          | screens   |
| `screen.recovered`         | A Mestra screen's problem is fixed                                                                                                                | screen          | screens   |
| `screen.update_waiting`    | A security update for a Mestra screen is waiting                                                                                                  | screen          | screens   |
| `takedown.done`            | No screen of a takedown is still waiting to go off                                                                                                | takedown        | screens   |
| `install_key.alert`        | An install key passes its expected screens, a revoked or expired key is tried, enrolments come too fast, or a screen reports its key was readable | none            | screens   |
| `plays.received`           | A Mestra screen's plays arrive. Opt-in: sent only to endpoints that ask for it by name                                                            | screen          | screens   |
| `screen.action_done`       | A remote action on a Mestra screen finished, failed or expired                                                                                    | screen          | screens   |
| `billing.paused`           | Billing moves to read-only                                                                                                                        | none            | usage     |
| `billing.resumed`          | Billing leaves read-only                                                                                                                          | none            | usage     |

The Mestra Player events are described in full in [Mestra Player webhooks](https://withmestra.com/docs/player/webhooks/).

The **area** is the permission an API key needs to read the event through [`GET /api/v1/events`](https://withmestra.com/docs/webhooks/testing/#list-events-from-the-api). It doesn't limit what an endpoint receives: an endpoint gets every type it subscribes to.

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

## `run.completed`

A run finishes.

- **Object:** run, at `/api/v1/runs/{id}`
- **Area to read it from the API:** runs

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "run.completed",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "run",
      "url": "https://app.withmestra.com/api/v1/runs/…"
    }
  }
}
```

## `run.failed`

A run fails.

- **Object:** run, at `/api/v1/runs/{id}`
- **Area to read it from the API:** runs

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "run.failed",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "run",
      "url": "https://app.withmestra.com/api/v1/runs/…"
    }
  }
}
```

## `run.cancelled`

A run is cancelled.

- **Object:** run, at `/api/v1/runs/{id}`
- **Area to read it from the API:** runs

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "run.cancelled",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "run",
      "url": "https://app.withmestra.com/api/v1/runs/…"
    }
  }
}
```

## `master.saved`

A master is saved or replaced. `data.editedFrom` is the version number the editor opened, when the version was saved from the editor (see [Editing a master](https://withmestra.com/docs/api/editing-a-master/)), and null when a design app saved it.

- **Object:** master, at `/api/v1/masters/{id}`
- **Area to read it from the API:** runs

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "master.saved",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "editedFrom": null,
    "object": {
      "id": "…",
      "type": "master",
      "url": "https://app.withmestra.com/api/v1/masters/…"
    }
  }
}
```

## `render.checked`

An output of a run is checked: against its campaign's rules, or, with no rule set, by the checks that need none. Fires once for each output file of a run that is checked: against its campaign's rules, or, for a run with no rule set, only by the checks that need none (an empty panel, a cut-off photo subject, text contrast). `passed` is whether it met every check made, `format` is the size's key, `failing` is how many checks it failed, and `job` names the run's job. A run made by a design app has no `data.object`. `receipt` is present only when the output passed a rule set's checks: Mestra's signed proof of that, which anyone can verify offline with the public keys at `/.well-known/mestra-receipt-keys.json` (an output that failed, or was checked with no rule set, has none).

- **Object:** run, at `/api/v1/runs/{id}`
- **Area to read it from the API:** runs

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "render.checked",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "failing": 0,
    "format": "square",
    "job": "…",
    "object": {
      "id": "…",
      "type": "run",
      "url": "https://app.withmestra.com/api/v1/runs/…"
    },
    "passed": true,
    "receipt": {
      "checksDigest": "…",
      "createdAt": "2026-10-22T03:14:15.000000Z",
      "fileSha256": "…",
      "formatKey": "square",
      "jobId": "…",
      "keyId": "2026-11",
      "orgId": "…",
      "passed": true,
      "ruleSetVersionId": "…",
      "signature": "…",
      "version": 1
    }
  }
}
```

## `size.edited`

A size is edited and saved in the editor or through the API. `data.object` is the run the size belongs to, named by the route that lists its editable sizes (`GET /api/v1/jobs/{id}/editable`). `size` is the size's key, `round` is the review round the edit became (null when it made none) and `pull` says what happened to the review, as the save's answer does: `ready`, `quiet`, `not_sent` or `superseded`. Fires once for each saved size, from the editor and from `PUT /api/v1/edit/save`, and not for a master saved from the editor (that is `master.saved`). A retried save (the same `idempotencyKey`) sends nothing more. Needs the Designs permission to be listed by `GET /events`.

- **Object:** run sizes, at `/api/v1/jobs/{id}/editable`
- **Area to read it from the API:** designs

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "size.edited",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "run_sizes",
      "url": "https://app.withmestra.com/api/v1/jobs/…/editable"
    },
    "pull": "ready",
    "round": 3,
    "size": "square"
  }
}
```

## `review.round_sent`

A review round goes out.

- **Object:** review campaign, at `/api/v1/reviews/campaigns/{id}`
- **Area to read it from the API:** reviews

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "review.round_sent",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "review_campaign",
      "url": "https://app.withmestra.com/api/v1/reviews/campaigns/…"
    }
  }
}
```

## `review.approved`

A reviewer approves.

- **Object:** review campaign, at `/api/v1/reviews/campaigns/{id}`
- **Area to read it from the API:** reviews

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "review.approved",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "review_campaign",
      "url": "https://app.withmestra.com/api/v1/reviews/campaigns/…"
    }
  }
}
```

## `review.changes_requested`

A reviewer asks for changes.

- **Object:** review campaign, at `/api/v1/reviews/campaigns/{id}`
- **Area to read it from the API:** reviews

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "review.changes_requested",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "review_campaign",
      "url": "https://app.withmestra.com/api/v1/reviews/campaigns/…"
    }
  }
}
```

## `comment.created`

A review comment is added. `data.comment_id` names the comment.

- **Object:** review campaign, at `/api/v1/reviews/campaigns/{id}`
- **Area to read it from the API:** reviews

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "comment.created",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "comment_id": "…",
    "object": {
      "id": "…",
      "type": "review_campaign",
      "url": "https://app.withmestra.com/api/v1/reviews/campaigns/…"
    }
  }
}
```

## `comment.resolved`

A review comment is resolved. `data.comment_id` names the comment.

- **Object:** review campaign, at `/api/v1/reviews/campaigns/{id}`
- **Area to read it from the API:** reviews

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "comment.resolved",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "comment_id": "…",
    "object": {
      "id": "…",
      "type": "review_campaign",
      "url": "https://app.withmestra.com/api/v1/reviews/campaigns/…"
    }
  }
}
```

## `export.ready`

A review export is ready.

- **Object:** export, at `/api/v1/reviews/campaigns/{id}/exports/{export}`
- **Area to read it from the API:** reviews

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "export.ready",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "export",
      "url": "https://app.withmestra.com/api/v1/reviews/campaigns/…/exports/…"
    }
  }
}
```

## `export.failed`

A review export fails.

- **Object:** export, at `/api/v1/reviews/campaigns/{id}/exports/{export}`
- **Area to read it from the API:** reviews

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "export.failed",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "object": {
      "id": "…",
      "type": "export",
      "url": "https://app.withmestra.com/api/v1/reviews/campaigns/…/exports/…"
    }
  }
}
```

## `publish.finished`

A publish to a screen network finishes, including a booking made in Mestra Player. `provider` is the screen network integration's id, `outcome` is `done`, `partial` or `failed`, and `items` and `failed` are counts. `receipts` has the signed receipt (the same object `render.checked` carries as `receipt`) of each published file that passed a rule set's checks; a file that did not has none. When a publication has too many receipts for one event, `receipts` is left out and `receiptsOmitted` (how many) and `receiptsAt` (the publication's route) take its place: read the items' `receipt` there. The event carries ids and counts only, no customer name. The publication it points at, read from the API, names its `customer` (id and name), `priority` and `policy`.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "publish.finished",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "failed": 2,
    "items": 12,
    "outcome": "partial",
    "provider": "screen-network",
    "receipts": [
      {
        "checksDigest": "…",
        "createdAt": "2026-10-22T03:14:15.000000Z",
        "fileSha256": "…",
        "formatKey": "square",
        "jobId": "…",
        "keyId": "2026-11",
        "orgId": "…",
        "passed": true,
        "ruleSetVersionId": "…",
        "signature": "…",
        "version": 1
      }
    ]
  }
}
```

## `dynamic.summary`

Once a day for a campaign whose variants changed. `campaign` is the campaign's key, `swaps` is how many times the artwork was switched on the previous day (UTC) and `rows` is how many different variants were chosen. Sent once a day, only for a campaign whose artwork was switched.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "dynamic.summary",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "campaign": "spring-sale",
    "rows": 3,
    "swaps": 6
  }
}
```

## `booking.submitted`

A customer submits artwork for a Network booking. Fires when the booking moves to review, including a resubmission after changes. Network booking: `network` is the network's slug and `booking_id` the booking's id.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "booking.submitted",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "booking_id": "…",
    "network": "acme-centres"
  }
}
```

## `booking.approved`

Staff approve a Network booking. Network booking: `network` is the network's slug and `booking_id` the booking's id.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "booking.approved",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "booking_id": "…",
    "network": "acme-centres"
  }
}
```

## `booking.live`

A Network booking is live on screens with every size live. Network booking: `network` is the network's slug and `booking_id` the booking's id. Fires only when every size is live, once the booking reaches that state; a booking with sizes held back fires `booking.partly_live` instead, and `booking.live` when they are released or replaced. Fires again if the booking goes live again after Stop all.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "booking.live",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "booking_id": "…",
    "network": "acme-centres"
  }
}
```

## `booking.partly_live`

A Network booking is on screens with some sizes held back. Network booking: `network` is the network's slug and `booking_id` the booking's id. `live` and `held` are the counts of sizes live and held back. Fires when the booking reaches screens with some sizes held, and again each time it returns to that state.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "booking.partly_live",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "booking_id": "…",
    "held": 1,
    "live": 2,
    "network": "acme-centres"
  }
}
```

## `booking.taken_down`

Staff take a Network booking down. Network booking: `network` is the network's slug and `booking_id` the booking's id.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "booking.taken_down",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "booking_id": "…",
    "network": "acme-centres"
  }
}
```

## `booking.held`

Sizes of a Network booking were held back from screens. Network booking: `network` is the network's slug and `booking_id` the booking's id. Fires once for each publish that held anything back. The booking reads as partly live until the held sizes are released or replaced.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** campaigns

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "booking.held",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "booking_id": "…",
    "network": "acme-centres"
  }
}
```

## `billing.paused`

Billing moves to read-only. `state` is the state it moved to, `read_only`.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** usage

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "billing.paused",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "state": "read_only"
  }
}
```

## `billing.resumed`

Billing leaves read-only. `state` is the state it moved to, such as `active` or `trial`.

- **Object:** none. The details are in `data`.
- **Area to read it from the API:** usage

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "billing.resumed",
  "created": "2026-10-22T03:14:15Z",
  "data": {
    "state": "active"
  }
}
```

## `ping`

Sent by **Send test event** in the panel. It has no object. It goes only to the endpoint you test, and you can't subscribe to it.

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "ping",
  "created": "2026-10-22T03:14:15Z",
  "data": {}
}
```
