Jun 3, 2022
Cardano Webhooks — Listen to on-chain events in real-time using Tangocrypto Notify.
NOTIFY (WEBHOOKS)
With Notify you will be able to integrate production-ready notifications with our webhooks and SDKs integrations. Get access to all of the blockchain events your users might care about, like successful transactions, payments, minted blocks by a pool, new delegations and whatnot.
- Payments and transactions: Allow sending notifications to users to know when their deposits, purchases, in-game actions or other on-chain activity has officially occurred.
- Address Activity Webhooks: Let your users know when transaction activity occurs on their address. No more refreshing the page or having to use the dust to identify a payment.
- Smart Retries: Sometimes receiving endpoints fail or hang more often than you think. That’s why we provide automatic retries to ensure deliverability.
- Monitoring and debug: We log every triggered webhook so you can monitor their deliverability to different endpoints, disable failing ones and notify your customers.
- Development experience: Offer your users a great developer experience, including the ability to test and inspect their webhooks.
What are Webhooks?
A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both provider and consumer. Webhooks work by registering a URL to send notifications once certain events occur.
You can think that Webhooks are like a phone number that Tangocrypto calls to notify you of activity in Cardano. The activity could be a payment to an address or reaching a particular epoch. The webhook endpoint is the person answering that call who takes actions based upon the specific information it receives.
A webhook endpoint is just more code on your server, which could be written in Node.js, Go, Java, Ruby, or whatever. The webhook endpoint has an associated URL (e.g. https://myserver.com/callback). The Tangocrypto notifications are Event objects. This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. The webhook endpoint uses the event details to take any required actions, such as indicating that an NFT should be sent to a wallet.
NOTE
Webhooks vs. WebSockets: The difference between webhooks and WebSockets is that webhooks can only facilitate one-way communication between two services, while WebSockets can facilitate two-way communication between a user and a service, recognizing events and displaying them to the user as they occur.
Event standard structure
The Event structure always begins with the following parameters:
{
"id": "2921e3df-c671-4d20-b51b-d176d5c1e43g", //** Unique uuid per event .**
"api_version": "1.0", //**Represents the current Tangocrypto API version, which is v1.**
"webhook_id": "d012a60eccb54c2ba97484f98137be56", // identifies the webhook
"idempotency_key": "3b3359d0ccdb1d3d3ca8dbaa79cb5395b33c5bc52d782f3ea22904abef45d1j4", //**Specifies a unique ID used by Tangocrypto to recognize consecutive requests with the same data so that not to perform the same operation twice.**
"object": "event",
"create_date": 1633954086377,
"type": "payment", // event type
...
}id Unique identifier per Event.
api_version The event scheme you receive depends on the version of the Tangocrypto API. Currently, we use v1. When you set a subscription for an event while using v1 of the API, the callback will be returned according to v1 specifics. Each time we update our API to the next version you will have to reset your Event subscriptions so that they correspond to the newest version currently in use. To do that you'll need to remove the event subscription and set it up again. Otherwise, the callback response will be received in the format of the older API version it was set up in.
webhook_id The webhook_id indicates a reference to the webhook and It's is a unique code. Each time you set up an event subscription, the corresponding Event always has a parameter webhook_id.
idempotency_key Idempotency represents a process in computing and REST that a server uses to recognise subsequent retries of the same request where the returned result always remains the same. It is a security mechanism for retrying requests without the risk of performing the same operation more than once.
Such risks usually can occur when an API call is for some reason disrupted during processing (e.g. network connection error) and a response is not returned. In such cases, the API call would be retried. By including an idempotency_id in the initial request there is a guarantee that the specific action won’t be done more than once. The idempotency_id is generated only by Tangocrypto webhooks. It is added to the Event and is unique per triggered webhook.
Types of Webhooks
Tangocrypto offers 5 different types of webhooks:
- Payments
- Block
- Transaction
- Epoch
- Delegation
Callback requests sent from Tangocrypto are always POST and it contains a JSON payload;
1. Payment
The Payment Webhook allows you to track payments to an address. This provides your app with real-time state changes when an address sends or receives tokens.
Payload example:
{
"id": "3c23ff25-481c-4e3e-859b-f515135a49b0",
"data": {
"transaction": {
"id": "3776000",
"fee": "168317",
"hash": "e29b4f5e2650560ac61dfa3ccf311e020782d8ccdf295dbbf1cfe2e65583d417",
"size": 289,
"block": {
"id": "3372157",
"fees": "2104143",
"hash": "7fac4956202395c06028b442faba4f3fda68490e2eb7373bd9d0b7b212ff9e1f",
"pool": {
"url": "https://my-ip.at/atada.testnet-metadata-2.json",
"hash": "b4fba3c5a430634f2e5e7007b33be02562efbcd036c0cf3dbb9d9dbdf418ef27",
"name": "ATADA TestnetPool Austria",
"ticker": "ATADA",
"pool_id": "pool18yslg3q320jex6gsmetukxvzm7a20qd90wsll9anlkrfua38flr",
"homepage": "https://stakepool.at",
"description": "Testnet-Environment Pool ..."
},
"size": 6561,
"time": "Thu Feb 24 2022 12:52:38 GMT+0000 (Coordinated Universal Time)",
"op_cert": "f9096c23c3a3d8afd8d05467fed2bc75405cdbc27ba2106b55a585e414d26573",
"out_sum": "9793211682245",
"slot_no": 51337942,
"vrf_key": "vrf_vk1sleujze3zraykllkafvrxggcmpts3hp6zxrpazdkdzp9g07kkehsnmy8ka",
"block_no": 3345852,
"epoch_no": 189,
"tx_count": "11",
"next_block": null,
"slot_leader": "pool18yslg3q320jex6gsmetukxvzm7a20qd90wsll9anlkrfua38flr",
"confirmations": 1,
"epoch_slot_no": 59542,
"previous_block": 3345851
},
"deposit": "0",
"out_sum": "948312856",
"block_id": "3372157",
"block_index": 2,
"script_size": 0,
"invalid_before": null,
"valid_contract": true,
"invalid_hereafter": "51359405"
},
"from": [{
"address": "addr_test1qqvelqlqk94qm9syd40mpqkvdvk0z8ka8mt7e2sfcrq07rmazcna98r9s350vpnyghfsuqk2y29yq88tdcvwm8j0p5dqsg32es",
"hash": "d6ef469d198fbf62a5b9860ba9295b9c9fddb80078e975ba032653f66b070b51",
"index": 1,
"value": "948481173",
"smart_contract": false,
"assets": []
}],
"to": [{
"address": "addr_test1qz5xdujk7unjmyrvqazy7l4w9dzxxfgt48ppv9tsjwywrzckyjqzaxt9rkqxc62m7tcdfylykzzjktqzlwssxfl3mlyqafvh99",
"hash": "e29b4f5e2650560ac61dfa3ccf311e020782d8ccdf295dbbf1cfe2e65583d417",
"index": 0,
"value": "2564320",
"smart_contract": false,
"assets": []
},
{
"address": "addr_test1qqvelqlqk94qm9syd40mpqkvdvk0z8ka8mt7e2sfcrq07rmazcna98r9s350vpnyghfsuqk2y29yq88tdcvwm8j0p5dqsg32es",
"hash": "e29b4f5e2650560ac61dfa3ccf311e020782d8ccdf295dbbf1cfe2e65583d417",
"index": 1,
"value": "945748536",
"smart_contract": false,
"assets": []
}
]
},
"type": "payment",
"object": "event",
"webhook_id": "532ce2beb2aa42738e1cc9c5f708168c",
"api_version": "1.0",
"create_date": 1645707159923,
"idempotency_key": "755a42b339274829aefd153285084132532ce2beb2aa42738e1cc9c5f708168c",
"network": "testnet"
}2. Block
This event is triggered every time a new block is created.
Payload example:
{
"id": "7b7c0d8a-8885-46d6-8e05-0d0802d95473",
"data": {
"id": "6864165",
"fees": "17182282",
"hash": "641aa7bcd185e036d6a379d4908639d436a540158d1db6debd0e2c3b2fa7c8cd",
"pool": {
"url": "https://ccwallet.io/ccw.metadata.210713.json",
"hash": "924ec324a9d2d172cd3fe44fbbb526e5c6bea677fb7276f07387c847dfe9026d",
"name": "TITANstaking #2",
"ticker": "TITAN",
"pool_id": "pool19pyfv4xnln8x4l7auw0n0skk3hd97shun707hrw5d4s553ys74x",
"homepage": "https://www.titanstaking.io",
"description": "For a TITAN strong Cardano network. Based in Germany. 💪 Join us! Telegram: https://t.me/titanstakingio - Twitter: https://twitter.com/titanstaking"
},
"size": 58970,
"time": "Fri Feb 04 2022 11:45:09 GMT+0000 (Coordinated Universal Time)",
"op_cert": "400345da097b2eb0194b4a76f87b6853b07e8b96b5de30b671b0e83c54530cd3",
"out_sum": "10738455237",
"slot_no": 52408818,
"vrf_key": "vrf_vk19kgvazgrvr9gstsk2qn0vz0hc9x8yn3lqdymzgztm92qk6r4q9asksen0h",
"block_no": 6840368,
"epoch_no": 318,
"tx_count": "37",
"next_block": null,
"slot_leader": "pool19pyfv4xnln8x4l7auw0n0skk3hd97shun707hrw5d4s553ys74x",
"confirmations": 1,
"epoch_slot_no": 396018,
"previous_block": 6840367
},
"type": "block",
"object": "event",
"webhook_id": "98c7051ff06b4651949466655ef974fe",
"api_version": "1.0",
"create_date": 1643975112334,
"idempotency_key": "53a957187a4a4dd888b6839ea2d4452298c7051ff06b4651949466655ef974fe",
"network": "mainnet"
}3. Transaction
This event is triggered every time a new transaction is added to the blockchain.
Payload example:
{
"id": "123c4446-7a4f-4e8b-8baf-3c1437101859",
"data": {
"id": "3344667",
"fee": "305781",
"hash": "057585b42409a71c34d664e945acb92f30f09f966c5d18f098881c2dbf909d6f",
"size": 2825,
"block": {
"id": "3275904",
"fees": "1582516",
"hash": "00fd351c00be3f1775361de12576d51ee582157e330d1ebe596498295a46d02e",
"pool": {
"url": null,
"hash": null,
"raw_id": "7679567d0559ed3df7cb54a848b9568b04d1976b9926d54ae9efdd3f",
"pool_id": "pool1weu4vlg9t8knma7t2j5y3w2k3vzdr9mtnynd2jhfalwn76nwh48"
},
"size": 6980,
"time": "Wed Jan 19 2022 23:11:35 GMT+0000 (Coordinated Universal Time)",
"op_cert": "60ffa1e3c1ab6d03a5447d2f40ab023dbce45b13f0e372d63a964d31c7ee6079",
"out_sum": "18474206426",
"slot_no": 48264679,
"vrf_key": "vrf_vk1mzhz5k03lahvx0gdlqtplkyasgzn8w2cpf8y8a8f76nzskptzzhqdqyyq3",
"block_no": 3251329,
"epoch_no": 182,
"tx_count": "8",
"next_block": null,
"slot_leader": "pool1weu4vlg9t8knma7t2j5y3w2k3vzdr9mtnynd2jhfalwn76nwh48",
"confirmations": 1,
"epoch_slot_no": 10279,
"previous_block": 3251328
},
"deposit": "0",
"out_sum": "1591350310",
"block_id": "3275904",
"block_index": 1,
"script_size": 2014,
"invalid_before": "48264456",
"valid_contract": true,
"invalid_hereafter": "48278855"
},
"type": "transaction",
"object": "event",
"webhook_id": "5ef8985b5ee74b4388f324293df17173",
"api_version": "1.0",
"create_date": 1642633895460,
"idempotency_key": "5wIH/+H/cOj3K+gv3zOek89bEbIXDgxz5ef8985b5ee74b4388f324293df17173"
}4. Epoch
Get notified when an epoch starts.
Payload example:
{
"no": 178,
"start_time": "2022-01-04T20:20:24.000Z"
}5. Delegation
This allows you to track delegations in the specified pool by its ticker or pool ID.
Payload Example:
{
"id": "d0cf3218-761f-4ca1-900b-7750fb66fb59",
"data": {
"id": 97463,
"pool": {
"url": "https://apex.nextvm.net/test/testpoolMetadata.json",
"hash": "f5ac677b58443ed2c9c9d53aa56652e71a132679e67ed9068f0227867172faf4",
"name": "ApexTestPool",
"raw_id": "5f5ed4eb2ba354ab2ad7c8859f3dacf93564637a105e80c8d8a7dc3c",
"ticker": "APEXT",
"pool_id": "pool1ta0df6et5d22k2khezze70dvly6kgcm6zp0gpjxc5lwrce0seyq",
"homepage": "https://cardano-apexpool.github.io/test/",
"description": "Apex Cardano Test Pool"
},
"tx_id": 3340342,
"addr_id": 402710,
"slot_no": 48240615,
"redeemer_id": null,
"pool_hash_id": 1030,
"active_epoch_no": 183
},
"type": "delegation",
"object": "event",
"webhook_id": "7c827ccd2d524eb5aadf1e5a391077aa",
"api_version": "1.0",
"create_date": 1642609833343,
"idempotency_key": "p90C0LTvk1XX1Ha8+JDPzzFfybhxJYYt7c827ccd2d524eb5aadf1e5a391077aa"
}Trigger Rules
You can create rules or trigger conditions for every webhook. You can create rules through the Tangocrypto Dashboard or the API. Every rule is composed of a field, a value and an operator. All the conditions have to be met for the webhook to be triggered. Rules are optional; depending on the number of rules and their parameters, whether the webhook will be triggered or not.
Example Trigger the webhook when the address receives more than 5 RBERRY tokens:
curl --location --request POST 'https://cardano-testnet.tangocrypto.com/<app-id>/v1/webhooks' \
--header 'content-type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data-raw '{
"type": "payment",
"name": "Payment webhook",
"network": "testnet",
"description": "Notify on payment with more than 5 RBERRY",
"callback_url": "https://webhook.site/74e4201b-d651-4971-8b74-ebd6b10fd967",
"address": "addr_test1qqqv50804vhe30n25awp6f8mhy9z3rrysva2mj4c9geaqyjr5gtdwq4yajng57kje93tt3fkc5k8cvvem7vl8yql2mcsxcstnx",
"rules": [
{
"field": "asset_name",
"operator": "=",
"value": "RBERRY"
},
{
"field": "quantity",
"operator": ">",
"value": "5"
}
]
}'Rules can be created also from the dashboard:
