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/.

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

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

Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9

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 - 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 - 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} - the method deletes a webhook and all its subscriptions.

POST https://rt.tonapi.io/webhooks/{webhook_id}/account-tx/subscribe - 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 - the method takes in a list of account IDs to unsubscribe from.

A request body:

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

Get a webhook's subscriptions

GET https://rt.tonapi.io/webhooks/{webhook_id}/account-tx/subscriptions?offset=0&limit=10

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

POST https://rt.tonapi.io/webhooks/{webhook_id}/subscribe-new-contracts - when a new contract is deployed to the blockchain, TONAPI sends a POST request to the webhook URL.

Unsubscribe from events about new contract deployments

POST https://rt.tonapi.io/webhooks/{webhook_id}/unsubscribe-new-contracts - stop receiving a webhook notification when a new contract is deployed to the blockchain.

Note: This subscription will trigger webhooks for every message on the blockchain that contains the specified opcode — even if it's unrelated to your accounts.

POST https://rt.tonapi.io/webhooks/{webhook_id}/subscribe-msg-opcode/0x{opcode} - when a new transaction is happening with a message that contains a specific opcode in its body, TONAPI sends a POST request to the webhook URL.

Unsubscribe from messages with a specific opcode in a message body

POST https://rt.tonapi.io/webhooks/{webhook_id}/unsubscribe-msg-opcode/0x{opcode} - stop receiving a webhook notification when a new transaction is happening with a message that contains a specific opcode in its body.

Testnet webhooks

Available by domain https://rt-testnet.tonapi.io/{ur_as_in_mainnet}

Webhooks API

On this page