🧐 Create webhook

Code samples

POST /api/v1/webhooks

curl -X POST 'https://settla.net/api/v1/webhooks' \
  -H 'X-API-Key: $SETTLA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "coin": "TRX",
  "webhook_url": "https://example.com/webhook",
  "addresses": [
    "TLWKepDBC8RZjAhtWyNqASyzgyVyHUuS7o"
  ],
  "is_active": true
}'

Creates a new webhook for the authenticated user. The listed addresses are picked up by the blockchain scanners automatically; no further call is needed. Watching starts from the next block the scanner processes — earlier transactions are not replayed.

A subscription needs the address only: no private key, mnemonic or xpub is involved, so addresses generated in your own wallet are watched exactly like addresses issued through the API.

Delivery failures are counted: after 20 consecutive failed deliveries the webhook is switched off (is_active becomes 0) and stops receiving notifications until you re-enable it with a PUT request. A single failure does not count — only a job that has exhausted its retries.

Body parameter

{
  "coin": "TRX",
  "webhook_url": "https://example.com/webhook",
  "addresses": [
    "TLWKepDBC8RZjAhtWyNqASyzgyVyHUuS7o"
  ],
  "is_active": true
}

🛠️ Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» coin	body	string	true	Chain whose transactions trigger the webhook. One subscription covers a whole chain, not a single asset: `TRX` reports native TRX transfers as well as TRC-10 and TRC-20 token transfers (USDT included), with the asset given in the `currency` field of the notification. `ETH` currently reports native ETH transfers only — an incoming ERC-20 payment does not trigger a notification, so use USDT on Tron if you need token notifications today. `BTC` reports native transfers, one notification per matching output.
» webhook_url	body	string(uri)	true	Target URL to receive webhook POST requests. Must be a publicly reachable http/https address: loopback, link-local and private ranges are rejected with 422, and so is a host that resolves into one of them.
» addresses	body	[string]	true	Addresses to monitor. At least one entry is required and each entry is limited to 255 characters; the number of entries is not capped, but matching is linear in the size of the list, so keep a subscription under roughly 1000 addresses and split larger pools across several webhooks.

Example responses

201 Response

{
  "data": {
    "id": 1,
    "user_id": 10,
    "coin": "TRX",
    "webhook_url": "https://example.com/webhook",
    "addresses": [
      "TLWKepDBC8RZjAhtWyNqASyzgyVyHUuS7o"
    ],
    "secret": "whsec_4f8c1a9d7e2b6035c4a1f8d9e0b3c7a25f6e1d4c8b0a9372e5d6c1f804b3a7e29",
    "is_active": 1,
    "last_triggered_at": null,
    "deleted_at": null,
    "created_at": "2025-09-16T12:00:00.000000Z",
    "updated_at": "2025-09-16T12:00:00.000000Z"
  }
}

422 Response

{
  "errors": {
    "webhook_url": [
      "Адрес недоступен для вебхука: адрес разрешается в приватную сеть."
    ]
  }
}

🔁 Responses

Status	Meaning	Description	Schema
201	Created	Created	Inline
401	401	Missing or invalid API key	None
422	Unprocessable Entity	Validation failed	Inline

🔄 Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» data	object	false	none	none
»» id	integer	false	none	none
»» user_id	integer	false	none	none
»» coin	string	false	none	none
»» webhook_url	string(uri)	false	none	none
»» addresses	[string]	false	none	none
»» secret	string	false	none	Key the platform signs deliveries with. The whole string, `whsec_` prefix included, is the HMAC-SHA256 key; the signed message is `<X-Settla-Timestamp>.<raw body>`. Created together with the webhook and returned by every endpoint here — see the Receiving notifications page for verification code. Rotate it with `POST /api/v1/webhooks/{webhook}/secret`.
»» is_active	[oneOf]	false	none	Whether the webhook receives notifications. Beware of the type: this field is not normalised in API v1, so it comes back as the raw database value 0 or 1 — except in the response to a create request, which echoes the boolean you have just sent. Treat it as truthy rather than comparing it to `true`.
»» last_triggered_at	string(date-time)¦null	false	none	Reserved for the time of the last notification. Nothing writes it at the moment, so it is always null — do not use it to tell a live webhook from an idle one. The dashboard's webhook statistics show the actual delivery history.
»» deleted_at	string(date-time)¦null	false	none	Always null in responses; deleted webhooks are not returned.
»» created_at	string(date-time)	false	none	none
»» updated_at	string(date-time)	false	none	none

Status Code 422

Name	Type	Required	Restrictions	Description
» errors	object	false	none	Field name → list of messages.

Enumerated Values

Property	Value
coin	TRX
coin	BTC
coin	ETH