Типы событий

Webhook подписывается на одну или несколько категорий. Категория — это группа близких по смыслу типов событий (event_type). Внутри категории конкретный тип события передаётся в поле event_type тела запроса и используется для маршрутизации обработки на вашей стороне.

Категории

Категория	Описание	Префикс `event_type`
Transactions	Создание, подтверждение, изменение статуса транзакций	`transaction.*`
Vaults	Создание и изменение vault-аккаунтов	`vault.*`

Актуальный список — через API

Список категорий может расширяться. Текущий список доступен через эндпоинт:

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

Принцип сопоставления

Категория определяется по префиксу event_type — части до первой точки. Например, событие transaction.created имеет префикс transaction и попадает в категорию Transactions.

event_type            →  prefix         →  category
transaction.broadcast    transaction       Transactions
vault.renamed            vault             Vaults

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

Категория Transactions

События жизненного цикла транзакции. Имя события соответствует новому статусу транзакции (transaction.<status>), за исключением действия transaction.unfrozen — оно отправляется при разморозке независимо от того, к какому статусу транзакция возвращается из истории.

`event_type`	Когда отправляется
`transaction.pending`	Транзакция создана пользователем и отправлена на проверку политикой
`transaction.awaiting_approvals`	Политика требует ручного аппрува от одного или нескольких пользователей
`transaction.approved`	Транзакция одобрена политикой автоматически или после успешного аппрува
`transaction.declined`	Аппруверы отклонили транзакцию, исходный vault неактивен, либо ошибка реконсиляции в блокчейне
`transaction.expired`	Истёк таймаут аппрува или таймаут подготовки транзакции к подписанию
`transaction.blocked_by_policy`	Политика заблокировала транзакцию
`transaction.created`	Транзакция собрана и получила идентификатор; ожидается MPC-подпись
`transaction.failed`	Ошибка при подготовке транзакции на этапе `approved → created`
`transaction.awaiting_confirmation`	Транзакция подготовлена, ожидается MPC-подпись
`transaction.awaiting_broadcast`	Транзакция подписана и поставлена в очередь на отправку в блокчейн
`transaction.broadcast`	Транзакция отправлена в блокчейн-сеть
`transaction.finished`	Транзакция финализирована в блокчейне (или settlement входящего депозита)
`transaction.frozen`	Транзакция заморожена вручную оператором или автоматически по AML
`transaction.unfrozen`	Заморозка снята; статус восстановлен из истории. Текущий статус смотрите в `data.status`

Депозиты

Входящие транзакции (deposit), обнаруженные системой на блокчейне, минуют этапы политики, аппрува и подписания. Первое событие, которое вы получите по такой транзакции, — это её итоговый статус (как правило transaction.finished).

Структура поля data соответствует объекту транзакции из основного API — те же поля, что и в ответе GET /api/v1/transactions/{id}. См. OpenAPI-справочник.

Пример события transaction.broadcast

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "transaction.broadcast",
  "category": "Transactions",
  "timestamp": "2026-04-23T10:15:30Z",
  "data": {
    "id": "5e2f8d4e-1a23-4b67-9c8e-0a1b2c3d4e5f",
    "tx_hash": "0xabc...",
    "status": "broadcast",
    "amount": "500000000000000000",
    "formatted_amount": "0.5",
    "decimals": 18,
    "symbol": "ETH",
    "fee": "21000000000000",
    "formatted_fee": "0.000021",
    "fee_limit": "21000000000000",
    "from": { "address": "0x...", "workspace_id": "...", "vault_id": "...", "vault_name": "Main" },
    "to":   { "address": "0x...", "external": true },
    "created_at": "2026-04-23T10:14:50Z",
    "updated_at": "2026-04-23T10:15:30Z"
  }
}

Категория Vaults

События жизненного цикла vault-аккаунтов. Имя события всегда отражает выполненное действие.

`event_type`	Когда отправляется
`vault.created`	Создан новый vault-аккаунт
`vault.renamed`	Изменено имя vault-аккаунта
`vault.frozen`	Vault автоматически заморожен по результатам AML-проверки входящего депозита
`vault.unfrozen`	Заморозка vault снята администратором

Структура поля data соответствует объекту vault из основного API — те же поля, что и в ответе GET /api/v1/vault.

Пример события vault.created

{
  "event_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "event_type": "vault.created",
  "category": "Vaults",
  "timestamp": "2026-04-23T10:15:30Z",
  "data": {
    "id": "8b1f3a72-c4d5-4e6f-90ab-1234567890ab",
    "name": "Main BTC vault",
    "status": "active",
    "workspace_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "created_at": "2026-04-23T10:15:30Z",
    "updated_at": "2026-04-23T10:15:30Z",
    "auto_fuel": false
  }
}

Гарантии и порядок

At-least-once: одно и то же событие может быть доставлено повторно. Используйте event_id (или заголовок X-Webhook-Event-Id) как ключ идемпотентности.
Без строгого порядка: события не упорядочены между собой. Полагайтесь на текущий статус внутри data.status, а не на последовательность типов. Если важна актуальность, читайте состояние через REST API по data.id.
Несколько событий по одной транзакции: за время жизни транзакция меняет статус несколько раз (например, pending → approved → created → awaiting_confirmation → broadcast → finished), и на каждое изменение отправляется отдельное событие.

Подписка на категории

Список категорий передаётся при создании или обновлении webhook:

{
  "categories": ["Transactions", "Vaults"]
}

Подписывайтесь только на нужные категории

Чем меньше событий вы получаете, тем меньше шум на стороне приложения и нагрузка на ваш сервер. При замене списка категорий через PUT старая подписка полностью заменяется новой.