Перейти к содержанию

Регистрация webhook

На этой странице — как создать, посмотреть, обновить и удалить webhook через REST API.

Доступ по ролям

Все операции управления webhook доступны пользователям со следующими ролями:

Роль Просмотр (список, детали, история) Управление (создание, обновление, удаление, replay)
Owner
Admin
Non-Signing Admin

Эндпоинт публичного ключа

GET /api/v1/webhooks/signing-key доступен без авторизации — это нужно для верификации подписи на стороне получателя. См. Верификация подписи.

Заголовки запроса

Все запросы к API webhook (кроме получения публичного ключа) требуют:

Заголовок Значение
Authorization Bearer <JWT-токен>
X-Workspace-Id UUID рабочего пространства
Content-Type application/json (для запросов с телом)

Создать webhook

curl -X POST https://gateway.pert.paranoid.security/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "description": "Уведомления о транзакциях",
    "categories": ["Transactions"]
  }'

Параметры тела

Поле Тип Обязательное Описание
url string да HTTPS-адрес, на который Pert будет отправлять события
description string нет Произвольное описание для удобства управления
categories string[] да Список категорий событий (см. Типы событий)
status string нет Начальный статус: active (по умолчанию) или inactive. Изменяется потом через PUT

Ответ — 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://your-server.com/webhook",
  "description": "Уведомления о транзакциях",
  "status": "active",
  "categories": ["Transactions"],
  "created_at": "2026-04-23T10:15:30Z",
  "updated_at": "2026-04-23T10:15:30Z"
}
Ограничения на URL

URL должен использовать схему https и резолвиться в публичный IP-адрес. Адреса в приватных сетях (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback (127.0.0.0/8, ::1), link-local, multicast и unspecified блокируются на этапе создания webhook для защиты от SSRF-атак.

Самоподписанные TLS-сертификаты не принимаются — используйте сертификаты от доверенных CA.

Получить список

curl https://gateway.pert.paranoid.security/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Возвращает массив webhook текущего рабочего пространства.

Получить webhook

curl https://gateway.pert.paranoid.security/api/v1/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Если webhook не существует или принадлежит другому рабочему пространству — вернётся 404 Not Found.

Обновить webhook

В теле запроса указывайте только те поля, которые хотите изменить.

curl -X PUT https://gateway.pert.paranoid.security/api/v1/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook-v2",
    "categories": ["Transactions", "Vaults"]
  }'

Параметры тела

Поле Тип Описание
url string Новый HTTPS-адрес
description string Новое описание
status string active или inactive
categories string[] Новый список категорий (полностью заменяет предыдущий)

Статусы webhook

Статус Что означает
active Webhook получает события
inactive Webhook не получает события (выключен вручную). Можно вернуть в active через PUT
disabled Webhook отключён автоматически после 50 ошибок подряд. См. Автоотключение

Возврат disabled-webhook в работу

Чтобы реактивировать webhook в статусе disabled, передайте {"status": "active"}. Перед этим — устраните причину сбоев на своей стороне, иначе webhook отключится снова.

Удалить webhook

curl -X DELETE https://gateway.pert.paranoid.security/api/v1/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Возвращает 204 No Content при успехе или 404 Not Found, если webhook не существует.

Список доступных категорий

curl https://gateway.pert.paranoid.security/api/v1/webhooks/categories \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Возвращает актуальный список категорий, на которые можно подписаться. Подробнее — на странице Типы событий.

Ограничения

Параметр Значение
Максимум webhook на рабочее пространство 10
Протокол URL Только HTTPS
Запрещённые адреса назначения loopback, private, link-local, multicast, unspecified
Минимальное количество категорий 1