Вебхук

Куда приходят события, алерты о низком балансе газ-кошелька и секрет подписи. Сами события — на странице События вебхука.

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

GET/v1/webhook

Ответы

Код	Описание
`200`	Настройка вебхука. Возвращает Webhook.
`401`	`unauthorized` — нет API-ключа, он неизвестен или отозван.
`403`	`partner_disabled` — аккаунт партнёра отключён.
`404`	`not_found` — вебхук не задан.

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

curl "https://api-testnet.portuna.io/v1/webhook" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Пример ответа

{
  "url": "https://processing.example/hooks/sweeps",
  "secret": "whsec_q8Kx2mR4tY7uI0oP3aS6dF9gH1jK5lZ8xC2vB4nM7qW",
  "low_balance": [
    {
      "chain_id": 11155111,
      "threshold": "20000000000000000",
      "low": false
    }
  ]
}

Задать вебхук и алерты о низком балансе

PUT/v1/webhook

Задаёт адрес, куда приходят события, и алерты о низком балансе газ-кошелька. Только публичные адреса по https, редиректы не выполняются. В ответе — secret, которым подписываются доставки: он создаётся вместе с вебхуком и при смене URL не меняется. low_balance заменяет все алерты: сети без порога в нём остаются без алерта, а запрос без low_balance снимает их все.

Тело запроса

Поле	Тип	Описание
`url` обязательно	string (uri)	Куда приходят события. До 2048 символов.
`low_balance`	массив object	Алерты о низком балансе газ-кошелька, не больше одного на сеть.
`low_balance[].chain_id` обязательно	ChainID	Идентификатор сети (EIP-155): `11155111` Sepolia и `97` BSC testnet с тестовым ключом, `1` Ethereum и `56` BSC с боевым.
`low_balance[].threshold` обязательно	Amount	Алерт, когда баланс газ-кошелька в этой сети опускается ниже этого порога, в wei; больше нуля.

Ответы

Код	Описание
`200`	Вебхук задан. Возвращает Webhook.
`400`	`invalid_json` — тело не JSON, больше 64 КиБ или в нём неизвестные поля.
`401`	`unauthorized` — нет API-ключа, он неизвестен или отозван.
`403`	`partner_disabled` — аккаунт партнёра отключён.
`422`	`invalid_url` — адрес не публичный или не `https`; `unknown_chain` — сеть в `low_balance` не поддерживается или указана дважды; `invalid_amount` — порог не целое число больше нуля.

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

curl -X PUT "https://api-testnet.portuna.io/v1/webhook" \
  -H "Authorization: Bearer $PORTUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://processing.example/hooks/sweeps",
  "low_balance": [
    {
      "chain_id": 11155111,
      "threshold": "20000000000000000"
    }
  ]
}'

Пример ответа

{
  "url": "https://processing.example/hooks/sweeps",
  "secret": "whsec_q8Kx2mR4tY7uI0oP3aS6dF9gH1jK5lZ8xC2vB4nM7qW",
  "low_balance": [
    {
      "chain_id": 11155111,
      "threshold": "20000000000000000",
      "low": false
    }
  ]
}

Удалить вебхук

DELETE/v1/webhook

Удаляет вебхук и его алерты о низком балансе. Недоставленные события отбрасываются: в журнале доставки они становятся failed. Вебхук, заданный заново, получает новый секрет.

Ответы

Код	Описание
`204`	Удалён.
`401`	`unauthorized` — нет API-ключа, он неизвестен или отозван.
`403`	`partner_disabled` — аккаунт партнёра отключён.
`404`	`not_found` — вебхук не задан.

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

curl -X DELETE "https://api-testnet.portuna.io/v1/webhook" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Журнал доставки вебхуков

GET/v1/webhook/deliveries

События партнёра, новые первыми, и как прошла их доставка.

Параметры

Имя	Где	Тип	Описание
`limit`	query	integer	Сколько строк на странице. От 1 до 200. По умолчанию `50`.
`cursor`	query	string	`next_cursor` прошлой страницы; для первой страницы не нужен.

Ответы

Код	Описание
`200`	Страница событий. Возвращает поля ниже.
`400`	`invalid_query` — параметр запроса не подходит; какой — в `message`.
`401`	`unauthorized` — нет API-ключа, он неизвестен или отозван.
`403`	`partner_disabled` — аккаунт партнёра отключён.

Тело ответа

Поле	Тип	Описание
`items` обязательно	массив WebhookDelivery
`next_cursor` обязательно	NextCursor	Курсор следующей страницы; на последней — `null`.

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

curl "https://api-testnet.portuna.io/v1/webhook/deliveries?limit=2" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Пример ответа

{
  "items": [
    {
      "id": "4b8e0d6a-2c1f-4e37-9a55-0f6d3b2e1c84",
      "event": "webhook.test",
      "status": "pending",
      "attempts": 2,
      "last_status_code": 502,
      "last_error": "status 502",
      "created_at": "2026-10-11T08:00:00Z",
      "delivered_at": null,
      "next_attempt_at": "2026-10-11T08:00:31Z"
    },
    {
      "id": "9c41e7d2-58a3-4b0f-a6d1-2e7f3c9b8a05",
      "event": "sweep.swept",
      "status": "delivered",
      "attempts": 1,
      "last_status_code": 204,
      "last_error": null,
      "created_at": "2026-10-11T07:03:02Z",
      "delivered_at": "2026-10-11T07:03:03Z",
      "next_attempt_at": null
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0xMVQwNzowMzowMloiLCJpZCI6IjljNDFlN2QyIn0"
}

Отправить тестовое событие

POST/v1/webhook/test

Ставит в очередь событие webhook.test. Оно подписывается и доставляется, как любое другое, и видно в журнале доставки.

Ответы

Код	Описание
`202`	Событие в очереди. Возвращает поля ниже.
`401`	`unauthorized` — нет API-ключа, он неизвестен или отозван.
`403`	`partner_disabled` — аккаунт партнёра отключён.
`404`	`not_found` — вебхук не задан.

Тело ответа

Поле	Тип	Описание
`id` обязательно	string (uuid)	`id` события — тот же, что в доставке и в журнале доставки.

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

curl -X POST "https://api-testnet.portuna.io/v1/webhook/test" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Пример ответа

{
  "id": "4b8e0d6a-2c1f-4e37-9a55-0f6d3b2e1c84"
}