Перейти к содержимому

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

Узнайте, как настроить шаблоны сообщений вебхуков, чтобы извлекать данные из входящих 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"]}
    ]
  }
}

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

text
*
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.

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

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

Подробнее

Полная документация: GJSON Path Syntax

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

Входящие payload могут содержать поле level, которое управляет доставкой push-уведомления: имя (silent, low, default, high, critical) или целое число (-2..2). См. Уровни приоритета сообщений.

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

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

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

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

Вебхук может добавить до 3 кнопок действий к каждому создаваемому им уведомлению. Задайте поле actions (JSON-строка) при создании или обновлении вебхука — см. Создание вебхука → Шаблон кнопок действий.

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)). Как и при разборе уровня, проверка мягкая: некорректная кнопка отбрасывается сама по себе, а остальные кнопки и уведомление всё равно доставляются.

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

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

bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
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
import requests

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

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

Документация Pocket Alert