Webhook

Where events go, the low balance alerts of your gas wallet, and the signing secret. The events themselves: Webhook events.

Get the webhook

GET/v1/webhook

Responses

Status	Description
`200`	Your webhook settings. Returns Webhook.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.
`404`	`not_found`: no webhook is set.

Example request

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

Example response

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

Set the webhook

PUT/v1/webhook

Sets the URL events go to and the low balance alerts of your gas wallet. Only public https addresses; redirects are not followed. The response carries the secret that signs deliveries: it is created with the webhook and stays the same when the URL changes. low_balance replaces all the alerts: chains without a threshold there get no alert, and a request without low_balance removes them all.

Request body

Field	Type	Description
`url` required	string (uri)	Where events go. Up to 2048 characters.
`low_balance`	array of object	Low balance alerts of your gas wallet, at most one per chain.
`low_balance[].chain_id` required	ChainID	The chain’s id (EIP-155): `11155111` Sepolia and `97` BSC testnet with a test key, `1` Ethereum and `56` BSC with a live key.
`low_balance[].threshold` required	Amount	Alert when the gas wallet’s balance on this chain falls below this, in wei; above zero.

Responses

Status	Description
`200`	The webhook is set. Returns Webhook.
`400`	`invalid_json`: the body is not JSON, is over 64 KiB or has unknown fields.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.
`422`	`invalid_url`: the URL is not a public `https` URL; `unknown_chain`: a chain in `low_balance` is not supported or is listed twice; `invalid_amount`: a threshold is not an integer above zero.

Example request

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"
    }
  ]
}'

Example response

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

Delete the webhook

DELETE/v1/webhook

Removes the webhook and its low balance alerts. Events not delivered yet are dropped: they show as failed in the delivery log. A webhook set again later gets a new secret.

Responses

Status	Description
`204`	Deleted.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.
`404`	`not_found`: no webhook is set.

Example request

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

List webhook deliveries

GET/v1/webhook/deliveries

Your events, newest first, and how their delivery went.

Parameters

Name	In	Type	Description
`limit`	query	integer	How many rows a page holds. From 1 to 200. Default: `50`.
`cursor`	query	string	The `next_cursor` of the previous page; none for the first page.

Responses

Status	Description
`200`	A page of events. Returns the fields below.
`400`	`invalid_query`: a query parameter is not valid; `message` says which.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.

Response body

Field	Type	Description
`items` required	array of WebhookDelivery
`next_cursor` required	NextCursor	The cursor of the next page; `null` on the last page.

Example request

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

Example response

{
  "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"
}

Send a test event

POST/v1/webhook/test

Queues a webhook.test event. It is signed and delivered like any other event, and shows in the delivery log.

Responses

Status	Description
`202`	The event is queued. Returns the fields below.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.
`404`	`not_found`: no webhook is set.

Response body

Field	Type	Description
`id` required	string (uuid)	The event’s `id`, as in the delivery and in the delivery log.

Example request

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

Example response

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