# Webhooks

Get a signed message at your own web address whenever something happens in Mestra.

Webhooks tell your systems what happens in Mestra as it happens. When a run finishes, or a reviewer approves, Mestra sends a small message to a web address you choose. Your system can then fetch the details with the [API](https://withmestra.com/docs/api/).

Each message is an **event**. It says what happened and where to look. It doesn't carry your artwork, comment text, names or file names.

The events for screens that run Mestra Player are listed with the [Mestra Player webhooks](https://withmestra.com/docs/player/webhooks/).

## How it works

1. An owner adds an [endpoint](https://withmestra.com/docs/webhooks/endpoints/): an `https` address, and the events it wants.
2. Mestra sends each matching event to it as a `POST`, signed with the endpoint's secret.
3. Your system [checks the signature](https://withmestra.com/docs/webhooks/signatures/), answers with a `2xx` status, and does its work.
4. If it doesn't answer `2xx`, Mestra [tries again](https://withmestra.com/docs/webhooks/retries/).

An event looks like this:

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

The [event object](https://withmestra.com/docs/webhooks/events/) page describes every field, and [event types](https://withmestra.com/docs/webhooks/event-types/) lists them all.

## What you can see

Owners see two tabs under **Webhooks** in Mestra:

- **Endpoints:** each endpoint with its log of deliveries, a **Resend** button and **Send test event**.
- **Events:** every event from the last 30 days, with where it was delivered.

A key can also read the same events from the API. See [Test and resend](https://withmestra.com/docs/webhooks/testing/).

## Where to start

- [Set up an endpoint](https://withmestra.com/docs/webhooks/endpoints/)
- [Verify signatures](https://withmestra.com/docs/webhooks/signatures/)
- [Best practices](https://withmestra.com/docs/webhooks/best-practices/)

Only owners can add endpoints.
