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

Создание вебхука POST ​

Создайте новый вебхук, чтобы получать уведомления от внешних сервисов.

Эндпоинт ​

POST https://api.pocketalert.app/v1/webhooks

Аутентификация ​

Обязательно

Добавьте в запрос один из этих заголовков:

  • Token: <your-api-key> — получите его в разделе API-ключи
  • Authorization: Bearer <jwt-token> — из запроса войти

Запрос ​

Заголовки ​

ЗаголовокОбязательныйОписание
Token✅Ваш API-ключ
Authorization✅Bearer <jwt-token>

Параметры тела запроса ​

ПараметрТипОбязательныйОписание
namestring✅Название вебхука (например, "Sentry", "GitHub")
urlstring❌Слаг URL для приёма запросов https://p4a.me/wh/{url}. Если не указан, генерируется случайный слаг из 20 символов. Должен быть уникальным: занятый слаг возвращает 409
messagestring✅Шаблон сообщения (используйте * для исходного JSON)
application_idstring❌TID приложения для группировки сообщений
device_idstring❌TID целевого устройства (не указывайте, чтобы отправлять на все устройства)
default_levelstring | int❌Уровень приоритета по умолчанию для сообщений этого вебхука, если в данных не указан свой: название (silent, low, default, high, critical) или целое число (-2..2). См. уровни приоритета сообщений.
actionsstring❌JSON-шаблон кнопок действий. Имеет ту же структуру, что и действия сообщения, но label/value могут содержать плейсхолдеры %field.path%, которые подставляются из входящих данных. Сохраняется как JSON-строка. Платная функция: на бесплатных тарифах удаляется.

Шаблон кнопок действий ​

actions позволяет уведомлениям от вебхука содержать до 3 кнопок. Плейсхолдеры %field.path% подставляются из входящих данных (тот же синтаксис, что и в шаблоне сообщения):

json
[
  { "type": "view", "label": "Open issue", "value": "%issue.html_url%" },
  { "type": "http", "label": "Ack", "value": "{\"url\":\"https://ops.example.com/ack/%issue.id%\",\"method\":\"POST\"}" }
]

Шаблон проверяется при сохранении: это должен быть JSON-массив не более чем из 3 кнопок с корректным type. Кнопка без плейсхолдеров должна быть полностью валидной, иначе запрос вернёт 400.

После подстановки каждая кнопка проверяется так же, как действия сообщения. Кнопка, которая становится некорректной для конкретных данных, например кнопка view, у которой отсутствует поле с URL, отбрасывается сама по себе; остальные кнопки и сообщение доставляются.

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

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

Используйте %field.path%, чтобы извлекать значения из входящего JSON:

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

Подробные примеры см. в разделе настройки вебхука.

Пример запроса ​

bash
curl -X POST "https://api.pocketalert.app/v1/webhooks" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Push",
    "message": "Push to %repository.name%: %head_commit.message%",
    "application_id": "s9h1ekk5xb46jikthl"
  }'
javascript
const response = await fetch('https://api.pocketalert.app/v1/webhooks', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'GitHub Push',
    message: 'Push to %repository.name%: %head_commit.message%',
    application_id: 's9h1ekk5xb46jikthl'
  })
});

const webhook = await response.json();
console.log('Webhook URL:', `https://p4a.me/wh/${webhook.url}`);
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/webhooks',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'GitHub Push',
        'message': 'Push to %repository.name%: %head_commit.message%',
        'application_id': 's9h1ekk5xb46jikthl'
    }
)

webhook = response.json()
print(f"Webhook URL: https://p4a.me/wh/{webhook['url']}")
php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/webhooks', [
    'name' => 'GitHub Push',
    'message' => 'Push to %repository.name%: %head_commit.message%',
    'application_id' => 's9h1ekk5xb46jikthl',
]);

$webhook = $response->json();
echo 'Webhook URL: https://p4a.me/wh/'.$webhook['url'];

Ответ ​

Успешный ответ ​

201 Created

Вебхук успешно создан

ПолеТипОписание
tidstringУникальный идентификатор вебхука
namestringНазвание вебхука
urlstringСлаг URL вебхука — используйте его во внешних сервисах
messagestringШаблон сообщения
actionsstringJSON-шаблон кнопок действий (пустая строка, если не задан)
is_activebooleanАктивен ли вебхук
json
{
  "tid": "kblf7mh9j8jjyeh4fx",
  "name": "GitHub Push",
  "url": "cs994rqfkk8ljngt",
  "message": "Push to %repository.name%: %head_commit.message%",
  "actions": "",
  "application_tid": "qm47b9pzxzx7applfd0",
  "device_tid": "",
  "is_active": true,
  "created_at": "01.09.2023 22:38:48"
}

Использование вебхука

Настройте внешний сервис так, чтобы он отправлял POST-запросы на:

https://p4a.me/wh/{url}

Ответы с ошибками ​

СтатусОписание
400Некорректный запрос — отсутствует name или message, некорректный default_level или некорректный шаблон actions
401Не авторизован — токен неверный или отсутствует
403Доступ запрещён — достигнут лимит вебхуков вашего тарифа
404Не найдено — application_id или device_id не существует
409Конфликт — слаг url уже занят

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