Skip to main content
POST
/
v2
/
notifications
/
webhooks
Create Webhook
curl --request POST \
  --url https://api.tusky.io/v2/notifications/webhooks \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "events": [
    {}
  ],
  "balanceThreshold": "<string>"
}
'
{
  "id": "<string>",
  "url": "<string>",
  "events": [
    {}
  ],
  "active": true,
  "secret": "<string>",
  "createdAt": "<string>"
}
Create a webhook endpoint to receive event notifications via HTTP POST.

​
Request Body

​
url
string
required
The HTTPS URL to send webhook events to.
​
events
array
required
Event types to subscribe to: files.expiring, balance.low, bandwidth.limit_approaching, bandwidth.limit_reached, transactions.limit_approaching, transactions.limit_reached.
​
balanceThreshold
string
SUI balance threshold for balance.low events (e.g., "5.0").

​
Response

​
id
string
Webhook ID.
​
url
string
Webhook URL.
​
events
array
Subscribed events.
​
active
boolean
Whether the webhook is active.
​
secret
string
Signing secret for verifying payloads. Only returned once.
​
createdAt
string
ISO 8601 creation timestamp.

​
Example

curl -X POST https://api.tusky.io/v2/notifications/webhooks \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/tusky-webhook",
    "events": ["files.expiring", "balance.low", "transactions.limit_reached"],
    "balanceThreshold": "5.0"
  }'

​
Response

{
  "id": "wh_abc123",
  "url": "https://api.example.com/tusky-webhook",
  "events": ["files.expiring", "balance.low", "transactions.limit_reached"],
  "active": true,
  "secret": "whsec_xK9m2nP4qR7...",
  "createdAt": "2026-03-07T14:00:00Z"
}
The secret is only returned when the webhook is created. Store it securely — use it to verify webhook payload signatures.
Webhook payloads are signed with HMAC-SHA256 using the secret. Verify the X-Tusky-Signature header on incoming requests to ensure authenticity.