# Set up an endpoint

Add a web address that receives Mestra events, and keep its signing secret safe.

An endpoint is the web address Mestra sends events to. Only owners can add them.

## Add an endpoint

1. In Mestra, open **Webhooks** under **Developer**.
2. On the **Endpoints** tab, choose **Add endpoint**.
3. Enter the **URL**.
4. Add a **description** if you like (up to 100 characters).
5. Choose **All events**, or pick the [event types](https://withmestra.com/docs/webhooks/event-types/) you want.
6. Save, then copy the **signing secret**.

The secret starts with `whsec_`. Mestra shows it once. Store it where your receiver can read it, such as an environment variable or a secrets manager. If you lose it, roll it.

## The URL

- It must start with `https://` and use port 443.
- It can't contain a username or password.
- It must be a public address. Mestra doesn't send to private or internal addresses.
- Mestra doesn't follow redirects. Give the final address.
- It can be up to 2,048 characters.

## What Mestra sends

Each event arrives as a `POST` with the event as a JSON body and these headers:

| Header             | Value                                                              |
| ------------------ | ------------------------------------------------------------------ |
| `Content-Type`     | `application/json`                                                 |
| `User-Agent`       | `Mestra-Webhooks/1.0 (+https://withmestra.com/docs/webhooks/)`     |
| `Mestra-Event-Id`  | The event's `id`, the same as in the body.                         |
| `Mestra-Signature` | The [signature](https://withmestra.com/docs/webhooks/signatures/). |

Answer with any `2xx` status within 10 seconds. That marks the event delivered. Any other answer, a timeout or a redirect counts as a failure, and Mestra will [try again](https://withmestra.com/docs/webhooks/retries/).

## Change an endpoint

You can change an endpoint's URL, description and event types, switch it off and on, or delete it. Switching an endpoint off stops further sends to it. Switching it back on doesn't send the events it missed. To catch up, use the **Events** tab and [**Resend**](https://withmestra.com/docs/webhooks/testing/).

## Roll the secret

Choose **Roll secret** on an endpoint to make a new one. You choose how long the old secret keeps working: not at all, or up to 24 hours. While both are valid, each event carries a signature for each, so your receiver can switch over without dropping events. See [Verify signatures](https://withmestra.com/docs/webhooks/signatures/#rolling-a-secret).

Roll a secret if it may have leaked.
