# Настройки вебхуков

Узнайте, как настроить шаблоны сообщений вебхуков, чтобы извлекать данные из входящих JSON-payload.

## Синтаксис шаблона сообщения

При создании вебхука вы задаёте шаблон сообщения, который определяет, как входящие JSON-данные превращаются в push-уведомления.

### Базовые шаблоны

| Шаблон | Описание |
|--------|----------|
| `*` | Вывести весь JSON-payload |
| `%field%` | Извлечь поле верхнего уровня |
| `%object.field%` | Извлечь вложенное поле |
| `%array.0%` | Получить первый элемент массива |
| `%array.0.field%` | Получить поле элемента массива |
| `%%` | Литеральный `%`. Нужен только непосредственно перед словом, за которым идёт ещё один `%`, например `%cpu%%%`; знак `%`, за которым идёт пробел, как в `90% on %host%`, остаётся как есть |

Плейсхолдер никогда не содержит пробелов, поэтому знаки процента в обычном тексте не обрабатываются: `CPU over 90% on %host%` выводится как `CPU over 90% on db-1`.

## Примеры

### Пример JSON-payload

Рассмотрим такой входящий payload вебхука:

```json
{
  "event": {
    "title": "New Order",
    "message": "A new order has been placed with ID 12345",
    "tags": ["order", "new"],
    "users": [
      {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
      {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
      {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
    ]
  }
}
```

### Настройка шаблона

**Full JSON**

```text
*
```

**Extracted Fields**

```text
Title: %event.title%
Message: %event.message%
Tags: %event.tags%
Users: %event.users.0%
First user: %event.users.0.first% %event.users.0.last%
```

### Результат

```
Title: New Order
Message: A new order has been placed with ID 12345
Tags: ["order","new"]
Users: {"age":44,"first":"Dale","last":"Murphy","nets":["ig","fb","tw"]}
First user: Dale Murphy
```

## Популярные интеграции

### Вебхуки GitHub

```text
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%
```

### Отслеживание ошибок Sentry

Для внутренней интеграции, используемой как действие оповещения (issue alerts):

```text
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%
```

Добавьте кнопку `view` с `%data.event.web_url%`, чтобы открыть задачу. Устаревший плагин Webhooks отправляет другой payload: в нём используйте `%project_name%: %event.title%` и `%url%`.

### Оповещения Grafana

```text
⚠️ %state%: %title%

%message%

Status: %status%
```

### Uptime Robot

```text
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%
```

## Расширенный синтаксис путей

Для сложного извлечения данных из JSON мы используем [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

### Полезные шаблоны

| Шаблон | Описание |
|--------|----------|
| `%users.#%` | Количество элементов массива |
| `%users.#.first%` | Массив всех значений `first` |
| `%users.@reverse%` | Обратить порядок массива |
| `%data.@pretty%` | Форматированный вывод JSON |

> **Tip: Подробнее**
>
> Полная документация: [GJSON Path Syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## Уровень приоритета

Входящие payload могут содержать поле `level`, которое управляет доставкой push-уведомления: имя (`silent`, `low`, `default`, `high`, `critical`) или целое число (`-2`..`2`). См. [Уровни приоритета сообщений](https://info.pocketalert.app/api/messages/create.md#priority-levels).

Порядок определения (побеждает первое совпадение):

1. Поле `level` во входящем JSON-payload
2. `default_level` вебхука (задаётся при создании вебхука)
3. Уровень по умолчанию для приложения
4. `default` (обычный)

В отличие от прямого API, входящие данные вебхука обрабатываются мягко: нераспознанное значение `level` игнорируется (используются значения по умолчанию), а не отклоняется, поэтому оповещения никогда не теряются.

## Кнопки действий

Вебхук может добавить до 3 кнопок действий к каждому создаваемому им уведомлению. Задайте поле `actions` (JSON-строка) при создании или обновлении вебхука — см. [Создание вебхука → Шаблон кнопок действий](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

`label` и `value` поддерживают те же плейсхолдеры `%field.path%`, что и шаблон сообщения, поэтому кнопки можно формировать из входящего payload:

```json
[
  { "type": "view", "label": "Open PR", "value": "%pull_request.html_url%" },
  { "type": "http", "label": "Merge", "value": "{\"url\":\"https://ci.example.com/merge/%pull_request.number%\",\"method\":\"POST\"}" }
]
```

После подстановки каждая кнопка проверяется (`type` ∈ `view`/`http`/`copy`, для `view` и `http` нужен URL с `http(s)`). Как и при разборе уровня, проверка мягкая: некорректная кнопка отбрасывается сама по себе, а остальные кнопки и уведомление всё равно доставляются.

Кнопки действий — платная функция. На бесплатных тарифах они удаляются, а уведомление доставляется без них.

После создания вебхука его можно проверить:

**cURL**

```bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
```

**JavaScript**

```javascript
await fetch('https://p4a.me/wh/YOUR_WEBHOOK_URL', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    event: { title: 'Test', message: 'Hello World' }
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://p4a.me/wh/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
```

**PHP**

```php
Http::post('https://p4a.me/wh/YOUR_WEBHOOK_URL', [
    'event' => [
        'title' => 'Test',
        'message' => 'Hello World',
    ],
]);
```

Это отправит тестовое уведомление на ваши устройства с использованием настроенного шаблона сообщения.
