---
title: "Update alert preferences"
method: PUT
path: "/alerts/preferences"
tags: ["Alerts"]
---

# Update alert preferences

`PUT /alerts/preferences`

## Request

- Base URL: `https://api.percher.run`
- URL: `https://api.percher.run/alerts/preferences`
- Auth: HTTP bearer

Upserts the user's preferences. If `webhookUrl` is set (or changed), a new HMAC-SHA256 signing secret is generated and returned once in the response as `webhookSecret`. It is never shown again — the user must copy it into their receiver. Subsequent saves without a URL change keep the existing secret; saving a different URL rotates it; clearing the URL clears the secret.

Webhook payload format (POST to the configured URL):
- Body: `{ type, id, timestamp, data }` (JSON)
- Headers: `X-Percher-Event`, `X-Percher-Delivery`, `X-Percher-Timestamp`, `X-Percher-Signature: sha256=<hex>`
- Signature = HMAC-SHA256(secret, `${timestamp}.${body}`)
- Event types: `deploy.failed`, `deploy.succeeded`, `app.crashed`, `app.unhealthy`, `app.recovered`, `domain.expiring`, `security.finding`

## Response `200`

Updated preferences. If a new secret was generated, it is included as `webhookSecret`.

## Other responses

- `400`: Validation error
- `401`: Unauthorized

---

[API](https://skmtc.dev/percher/apis/percher-api.md) · [All operations](https://skmtc.dev/percher/apis/percher-api/llms.txt) · [OpenAPI document](https://skmtc.dev/percher/apis/percher-api/revisions/d9e7089c21e5?raw)