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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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.
{ "id": "evt_…", "object": "event", "type": "ping", "created": "2026-10-22T03:14:15Z", "data": {}}