Skip to content

Webhooks

Event types

Every event has the same shape. 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
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
billing.paused Billing moves to read-only none usage
billing.resumed Billing leaves read-only none usage

Events for screens that run Mestra Player (screen.*) are listed with the Mestra Player webhooks.

The Mestra Player events are described in full in Mestra Player webhooks.

The area is the permission an API key needs to read the event through GET /api/v1/events. 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), 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": {}
}