Создание вебхука POST
Создайте новый вебхук, чтобы получать уведомления от внешних сервисов.
Эндпоинт
POST https://api.pocketalert.app/v1/webhooksАутентификация
Обязательно
Добавьте в запрос один из этих заголовков:
Запрос
Заголовки
| Заголовок | Обязательный | Описание |
|---|---|---|
Token | ✅ | Ваш API-ключ |
Authorization | ✅ | Bearer <jwt-token> |
Параметры тела запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
name | string | ✅ | Название вебхука (например, "Sentry", "GitHub") |
url | string | ❌ | Слаг URL для приёма запросов https://p4a.me/wh/{url}. Если не указан, генерируется случайный слаг из 20 символов. Должен быть уникальным: занятый слаг возвращает 409 |
message | string | ✅ | Шаблон сообщения (используйте * для исходного JSON) |
application_id | string | ❌ | TID приложения для группировки сообщений |
device_id | string | ❌ | TID целевого устройства (не указывайте, чтобы отправлять на все устройства) |
default_level | string | int | ❌ | Уровень приоритета по умолчанию для сообщений этого вебхука, если в данных не указан свой: название (silent, low, default, high, critical) или целое число (-2..2). См. уровни приоритета сообщений. |
actions | string | ❌ | JSON-шаблон кнопок действий. Имеет ту же структуру, что и действия сообщения, но label/value могут содержать плейсхолдеры %field.path%, которые подставляются из входящих данных. Сохраняется как JSON-строка. Платная функция: на бесплатных тарифах удаляется. |
Шаблон кнопок действий
actions позволяет уведомлениям от вебхука содержать до 3 кнопок. Плейсхолдеры %field.path% подставляются из входящих данных (тот же синтаксис, что и в шаблоне сообщения):
[
{ "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%, остаётся без изменений |
Подробные примеры см. в разделе настройки вебхука.
Пример запроса
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"
}'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}`);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']}")$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
Вебхук успешно создан
| Поле | Тип | Описание |
|---|---|---|
tid | string | Уникальный идентификатор вебхука |
name | string | Название вебхука |
url | string | Слаг URL вебхука — используйте его во внешних сервисах |
message | string | Шаблон сообщения |
actions | string | JSON-шаблон кнопок действий (пустая строка, если не задан) |
is_active | boolean | Активен ли вебхук |
{
"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 уже занят |