Webhooks API
This section is a work in progress and will be updated and improved over time.
This feature is currently in beta and free to use. Once it exits beta, it will become a paid feature.
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
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.