Webhooks API

Webhooks API provides a way to subscribe to events that happen in the TON blockchain. This allows you to build applications that react to events in the blockchain.

Authentication

All methods of Webhooks API require a private API key. You can get a personal API key at https://tonconsole.com/ (opens in a new tab).

Webhooks API looks for an API key in two places in the following order:

1. In the Authorization header with the "Bearer scheme". For example:

Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9

2. In the "token" parameter of the query string. For example:

https://rt.tonapi.io/webhooks?token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9

API methods to manage webhooks

When a transaction happens on an account, TONAPI sends a POST request to a webhook URL. The request body contains the account's ID, the transaction's hash and LT. An example of a request body:

{
  "account_id":"0:8f2d840ec05d118f98459a057b1fcab535c57b9371222be15667fee932ceaf53",
  "lt":49739623000001,
  "tx_hash":"653e593d581ad40d5d0868fe5d60008e1bfe9d2d4c4fa6b2ee5cd458741d7b59"
}

Create webhook

POST https://rt.tonapi.io/webhooks (opens in a new tab) - the method creates a new webhook, configures its endpoint and returns a webhook ID. A webhook ID is used to manage subscriptions to account transactions.

A request body:

{
  "endpoint": "https://your-server.com/webhook"
}

A response example:

{
  "webhook_id": 5
}

List webhooks

GET https://rt.tonapi.io/webhooks (opens in a new tab) - the method returns all available webhooks: their IDs and endpoints. A response example:

{
  "webhooks": [
    { "id": 5, "endpoint": "https://your-server.com/webhook" },
    { "id": 6, "endpoint": "https://your-server.com/another-webhook" }
  ]
}

Delete a webhook

DELETE https://rt.tonapi.io/webhooks/{webhook_id} (opens in a new tab) - the method deletes a webhook and all its subscriptions.

Subscribe to account transactions

POST https://rt.tonapi.io/webhooks/{webhook_id}/account-tx/subscribe (opens in a new tab) - the method takes in a list of account IDs to subscribe to. When a new transaction happens on any of the accounts, TONAPI sends a POST request to the webhook URL.

A request body:

  {"accounts": [{"account_id": "0:6ccd325a858c379693fae2bcaab1c2906831a4e10a6c3bb44ee8b615bca1d220"}]}

Unsubscribe from account transactions

POST https://rt.tonapi.io/webhooks/{webhook_id}/account-tx/unsubscribe (opens in a new tab) - the method takes in a list of account IDs to unsubscribe from.

A request body:

  {"accounts": [{"account_id": "0:6ccd325a858c379693fae2bcaab1c2906831a4e10a6c3bb44ee8b615bca1d220"}]}

Get a webhook's subscriptions

GET https://rt.tonapi.io/webhooks/{webhook_id}/account-tx/subscriptions?offset=0&limit=10 (opens in a new tab)

A response example:

{
  "account_tx_subscriptions": [
    {
        "account_id": "0:6ccd325a858c379693fae2bcaab1c2906831a4e10a6c3bb44ee8b615bca1d220",
        "last_delivered_lt": 2900000001,
        "failed_at": "<time of failure>",
        "failed_lt": 2900000000,
        "failed_attempts": 4
    }
  ]
}