Webhooks API

🔄

This section is a work in progress and will be updated and improved over time.

🛠️

This feature is currently in beta.

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:

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 (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": ["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
    }
  ]
}

Subscribe to events about new contract deployments

POST https://rt.tonapi.io/webhooks/{webhook_id}/subscribe-new-contracts (opens in a new tab) - 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 (opens in a new tab) - stop receiving a webhook notification when a new contract is deployed to the blockchain.

Subscribe to messages with a specific opcode in a message body

POST https://rt.tonapi.io/webhooks/{webhook_id}/subscribe-msg-opcode/0x{opcode} (opens in a new tab) - 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} (opens in a new tab) - stop receiving a webhook notification when a new transaction is happening with a message that contains a specific opcode in its body.

Streaming API GraphQL