Tangocrypto
Search…
Using Webhooks
Listen for events on the Cardano network and automatically trigger reactions.

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.

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.

Types of Webhooks

Tangocrypto offers 4 different types of webhooks:
  1. 1.
    Payments
  2. 2.
    Block
  3. 3.
    Transaction
  4. 4.
    Epoch
  5. 5.
    Delegation
  6. 6.
    NFT API
Callback requests sent from Tangocrypto are always POST and it contains a JSON payload;

Event standard structure

The Event structure always begins with the following parameters:
1
{
2
"id": "2921e3df-c671-4d20-b51b-d176d5c1e43g", //** Unique uuid per event .**
3
"api_version": "1.0", //**Represents the current Tangocrypto API version, which is v1.**
4
"webhook_id": "d012a60eccb54c2ba97484f98137be56", // identifies the webhook
5
"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.**
6
"object": "event",
7
"create_date": 1633954086377,
8
"type": "payment", // event type
9
...
10
}
Copied!

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.

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
1
{
2
"id": "3c23ff25-481c-4e3e-859b-f515135a49b0",
3
"data": {
4
"transaction": {
5
"id": "3776000",
6
"fee": "168317",
7
"hash": "e29b4f5e2650560ac61dfa3ccf311e020782d8ccdf295dbbf1cfe2e65583d417",
8
"size": 289,
9
"block": {
10
"id": "3372157",
11
"fees": "2104143",
12
"hash": "7fac4956202395c06028b442faba4f3fda68490e2eb7373bd9d0b7b212ff9e1f",
13
"pool": {
14
"url": "https://my-ip.at/atada.testnet-metadata-2.json",
15
"hash": "b4fba3c5a430634f2e5e7007b33be02562efbcd036c0cf3dbb9d9dbdf418ef27",
16
"name": "ATADA TestnetPool Austria",
17
"ticker": "ATADA",
18
"pool_id": "pool18yslg3q320jex6gsmetukxvzm7a20qd90wsll9anlkrfua38flr",
19
"homepage": "https://stakepool.at",
20
"description": "Testnet-Environment Pool ..."
21
},
22
"size": 6561,
23
"time": "Thu Feb 24 2022 12:52:38 GMT+0000 (Coordinated Universal Time)",
24
"op_cert": "f9096c23c3a3d8afd8d05467fed2bc75405cdbc27ba2106b55a585e414d26573",
25
"out_sum": "9793211682245",
26
"slot_no": 51337942,
27
"vrf_key": "vrf_vk1sleujze3zraykllkafvrxggcmpts3hp6zxrpazdkdzp9g07kkehsnmy8ka",
28
"block_no": 3345852,
29
"epoch_no": 189,
30
"tx_count": "11",
31
"next_block": null,
32
"slot_leader": "pool18yslg3q320jex6gsmetukxvzm7a20qd90wsll9anlkrfua38flr",
33
"confirmations": 1,
34
"epoch_slot_no": 59542,
35
"previous_block": 3345851
36
},
37
"deposit": "0",
38
"out_sum": "948312856",
39
"block_id": "3372157",
40
"block_index": 2,
41
"script_size": 0,
42
"invalid_before": null,
43
"valid_contract": true,
44
"invalid_hereafter": "51359405"
45
},
46
"from": [{
47
"address": "addr_test1qqvelqlqk94qm9syd40mpqkvdvk0z8ka8mt7e2sfcrq07rmazcna98r9s350vpnyghfsuqk2y29yq88tdcvwm8j0p5dqsg32es",
48
"hash": "d6ef469d198fbf62a5b9860ba9295b9c9fddb80078e975ba032653f66b070b51",
49
"index": 1,
50
"value": "948481173",
51
"smart_contract": false,
52
"assets": []
53
}],
54
"to": [{
55
"address": "addr_test1qz5xdujk7unjmyrvqazy7l4w9dzxxfgt48ppv9tsjwywrzckyjqzaxt9rkqxc62m7tcdfylykzzjktqzlwssxfl3mlyqafvh99",
56
"hash": "e29b4f5e2650560ac61dfa3ccf311e020782d8ccdf295dbbf1cfe2e65583d417",
57
"index": 0,
58
"value": "2564320",
59
"smart_contract": false,
60
"assets": []
61
},
62
{
63
"address": "addr_test1qqvelqlqk94qm9syd40mpqkvdvk0z8ka8mt7e2sfcrq07rmazcna98r9s350vpnyghfsuqk2y29yq88tdcvwm8j0p5dqsg32es",
64
"hash": "e29b4f5e2650560ac61dfa3ccf311e020782d8ccdf295dbbf1cfe2e65583d417",
65
"index": 1,
66
"value": "945748536",
67
"smart_contract": false,
68
"assets": []
69
}
70
]
71
},
72
"type": "payment",
73
"object": "event",
74
"webhook_id": "532ce2beb2aa42738e1cc9c5f708168c",
75
"api_version": "1.0",
76
"create_date": 1645707159923,
77
"idempotency_key": "755a42b339274829aefd153285084132532ce2beb2aa42738e1cc9c5f708168c",
78
"network": "testnet"
79
}
Copied!

2. Block

This event is triggered every time a new block is created.
Payload example
1
{
2
"id": "7b7c0d8a-8885-46d6-8e05-0d0802d95473",
3
"data": {
4
"id": "6864165",
5
"fees": "17182282",
6
"hash": "641aa7bcd185e036d6a379d4908639d436a540158d1db6debd0e2c3b2fa7c8cd",
7
"pool": {
8
"url": "https://ccwallet.io/ccw.metadata.210713.json",
9
"hash": "924ec324a9d2d172cd3fe44fbbb526e5c6bea677fb7276f07387c847dfe9026d",
10
"name": "TITANstaking #2",
11
"ticker": "TITAN",
12
"pool_id": "pool19pyfv4xnln8x4l7auw0n0skk3hd97shun707hrw5d4s553ys74x",
13
"homepage": "https://www.titanstaking.io",
14
"description": "For a TITAN strong Cardano network. Based in Germany. πŸ’ͺ Join us! Telegram: https://t.me/titanstakingio - Twitter: https://twitter.com/titanstaking"
15
},
16
"size": 58970,
17
"time": "Fri Feb 04 2022 11:45:09 GMT+0000 (Coordinated Universal Time)",
18
"op_cert": "400345da097b2eb0194b4a76f87b6853b07e8b96b5de30b671b0e83c54530cd3",
19
"out_sum": "10738455237",
20
"slot_no": 52408818,
21
"vrf_key": "vrf_vk19kgvazgrvr9gstsk2qn0vz0hc9x8yn3lqdymzgztm92qk6r4q9asksen0h",
22
"block_no": 6840368,
23
"epoch_no": 318,
24
"tx_count": "37",
25
"next_block": null,
26
"slot_leader": "pool19pyfv4xnln8x4l7auw0n0skk3hd97shun707hrw5d4s553ys74x",
27
"confirmations": 1,
28
"epoch_slot_no": 396018,
29
"previous_block": 6840367
30
},
31
"type": "block",
32
"object": "event",
33
"webhook_id": "98c7051ff06b4651949466655ef974fe",
34
"api_version": "1.0",
35
"create_date": 1643975112334,
36
"idempotency_key": "53a957187a4a4dd888b6839ea2d4452298c7051ff06b4651949466655ef974fe",
37
"network": "mainnet"
38
}
Copied!

3. Transaction

This event is triggered every time a new transaction is added to the blockchain.
Payload example
1
{
2
"id": "123c4446-7a4f-4e8b-8baf-3c1437101859",
3
"data": {
4
"id": "3344667",
5
"fee": "305781",
6
"hash": "057585b42409a71c34d664e945acb92f30f09f966c5d18f098881c2dbf909d6f",
7
"size": 2825,
8
"block": {
9
"id": "3275904",
10
"fees": "1582516",
11
"hash": "00fd351c00be3f1775361de12576d51ee582157e330d1ebe596498295a46d02e",
12
"pool": {
13
"url": null,
14
"hash": null,
15
"raw_id": "7679567d0559ed3df7cb54a848b9568b04d1976b9926d54ae9efdd3f",
16
"pool_id": "pool1weu4vlg9t8knma7t2j5y3w2k3vzdr9mtnynd2jhfalwn76nwh48"
17
},
18
"size": 6980,
19
"time": "Wed Jan 19 2022 23:11:35 GMT+0000 (Coordinated Universal Time)",
20
"op_cert": "60ffa1e3c1ab6d03a5447d2f40ab023dbce45b13f0e372d63a964d31c7ee6079",
21
"out_sum": "18474206426",
22
"slot_no": 48264679,
23
"vrf_key": "vrf_vk1mzhz5k03lahvx0gdlqtplkyasgzn8w2cpf8y8a8f76nzskptzzhqdqyyq3",
24
"block_no": 3251329,
25
"epoch_no": 182,
26
"tx_count": "8",
27
"next_block": null,
28
"slot_leader": "pool1weu4vlg9t8knma7t2j5y3w2k3vzdr9mtnynd2jhfalwn76nwh48",
29
"confirmations": 1,
30
"epoch_slot_no": 10279,
31
"previous_block": 3251328
32
},
33
"deposit": "0",
34
"out_sum": "1591350310",
35
"block_id": "3275904",
36
"block_index": 1,
37
"script_size": 2014,
38
"invalid_before": "48264456",
39
"valid_contract": true,
40
"invalid_hereafter": "48278855"
41
},
42
"type": "transaction",
43
"object": "event",
44
"webhook_id": "5ef8985b5ee74b4388f324293df17173",
45
"api_version": "1.0",
46
"create_date": 1642633895460,
47
"idempotency_key": "5wIH/+H/cOj3K+gv3zOek89bEbIXDgxz5ef8985b5ee74b4388f324293df17173"
48
}
Copied!

4. Epoch

Get notified when an epoch starts.
Payload example
1
{
2
"no": 178,
3
"start_time": "2022-01-04T20:20:24.000Z"
4
}
Copied!

5. Delegation

This allows you to track delegations in the specified pool by its ticker or pool ID.
Payload Example
1
{
2
"id": "d0cf3218-761f-4ca1-900b-7750fb66fb59",
3
"data": {
4
"id": 97463,
5
"pool": {
6
"url": "https://apex.nextvm.net/test/testpoolMetadata.json",
7
"hash": "f5ac677b58443ed2c9c9d53aa56652e71a132679e67ed9068f0227867172faf4",
8
"name": "ApexTestPool",
9
"raw_id": "5f5ed4eb2ba354ab2ad7c8859f3dacf93564637a105e80c8d8a7dc3c",
10
"ticker": "APEXT",
11
"pool_id": "pool1ta0df6et5d22k2khezze70dvly6kgcm6zp0gpjxc5lwrce0seyq",
12
"homepage": "https://cardano-apexpool.github.io/test/",
13
"description": "Apex Cardano Test Pool"
14
},
15
"tx_id": 3340342,
16
"addr_id": 402710,
17
"slot_no": 48240615,
18
"redeemer_id": null,
19
"pool_hash_id": 1030,
20
"active_epoch_no": 183
21
},
22
"type": "delegation",
23
"object": "event",
24
"webhook_id": "7c827ccd2d524eb5aadf1e5a391077aa",
25
"api_version": "1.0",
26
"create_date": 1642609833343,
27
"idempotency_key": "p90C0LTvk1XX1Ha8+JDPzzFfybhxJYYt7c827ccd2d524eb5aadf1e5a391077aa"
28
}
Copied!

6. NFT API

This allows you to track when a sale is completed.
Payload Example
1
{
2
"id": "ec5ea629-25d1-4dd6-aedc-aae2a7e5bc5e",
3
"data": {
4
"saleId": "69c84acf0af6468aad42695109752691",
5
"tokens": [
6
{
7
"image": "ipfs://QmbR6vfPA9qrfpU5Zm81k5SMRdhE9yUVpCKPErGrbs8NcP",
8
"tx_id": "bcf3705786164225e2baf7634807d5e50c2f42c4c6ca0defe10e8a14294e5046",
9
"asset_name": "FACE#01"
10
}
11
],
12
"accountId": "ce0c3a8918284beab267c433d966385a",
13
"collectionId": "f5ee876c14a04c5092af43de09018c30"
14
},
15
"type": "nft",
16
"object": "event",
17
"webhook_id": "78ad7356e2d6472da14c5901b65691dd",
18
"api_version": "1.0",
19
"create_date": 1656261173901,
20
"idempotency_key": "3e61686a-2c05-4b08-8297-853ecb2b1cfb78ad7356e2d6472da14c5901b65691dd",
21
"network": "testnet"
22
}
Copied!

Webhooks testing

Testing with webhook.site

Check out this video on how to create a webhook and test it:
Webhook testing tutorial with webhook.site
Or follow the written steps below:
There are many websites you can use to test out webhooks. For example, you can use https://webhook.site/ and copy your unique URL. Once you have the URL, you can test using the following steps:
  1. 1.
    Navigate to your Tangocrypto dashboard​
  2. 2.
    Click "Create Webhook"
  3. 3.
    Fill the form with the unique URL generated in https://webhook.site/ and the address you want to monitor.
Create webhook in the dasboard
4. Now we send ADA to that address, here we are using ccvault to send 10 ADA from MyTestWallet1 to MyTestWallet2.
Transaction in Ccwallet
5. You should then see the result updated on website: https://webhook.site/​
Payment webhook

Local testing with a Node.js Express app

Check out this video on how to create a webhook and test with a local Node.js express app:
Webhook testing with a Node.js express app
Or follow the written steps below:
If we want to test the webhook in our computer and we are behind a proxy/NAT device or a firewall we need a tool like Ngrok. Below you can see the diagram of how this will work. Tangocrypto Notify will trigger the webhook and make a POST to Ngrok cloud, then the request is forwarded to your local Ngrok client who in turn forwards it to the Node.js app listening on port 8000.
Node.js Express app architecture
Go to https://ngrok.com/ create a free account, download the binary and connect to your account. Create a Node.js app with Express and paste the following code to receive the webhook:
1
// This example uses Express to receive webhooks
2
const express = require('express');
3
const app = express();
4
​
5
app.post('/callback', express.json({type: 'application/json'}), (request, response) => {
6
const event = request.body;
7
​
8
// Handle the event
9
switch (event.type) {
10
case 'payment':
11
console.log("*** Payment event ***");
12
console.log(event.data.payments);
13
break;
14
case 'epoch':
15
console.log("*** Epoch event ***");
16
17
break;
18
// ... handle other event types
19
default:
20
console.log(`Unhandled event type ${event.type}`);
21
}
22
​
23
// Return a response to acknowledge receipt of the event
24
response.json({received: true});
25
});
26
​
27
​
28
app.listen(8000, () => console.log('Running on port 8000'));
Copied!
Run the app with the following command:
1
node app.js
Copied!
The Express app will be listening on port 8000. To start an HTTP tunnel forwarding to your local port 8000 with Ngrok, run this next:
1
./ngrok http 8000
Copied!
You should see something like this:
1
ngrok by @inconshreveable (Ctrl+C to quit)
2
3
Session Status online
4
Account Tangocrypto (Plan: Free)
5
Version 2.3.40
6
Region United States (us)
7
Web Interface http://127.0.0.1:4040
8
Forwarding http://80b4-2a02-c7f-f20b-6800-71cf-18c9-c6f1-dc5.ngrok.io -> http://localhost:3005
9
Forwarding https://80b4-2a02-c7f-f20b-6800-71cf-18c9-c6f1-dc5.ngrok.io -> http://localhost:3005
10
11
Connections ttl opn rt1 rt5 p50 p90
12
0 0 0.00 0.00 0.00 0.00
Copied!
Copy the https Forwarding URL and append the /callback path and type the address you want to monitor.
If we transfer Ada to the address Tangocrypto Notify will detect the payment and the webhook will be triggered. Now we can receive the event on our local server. The response should be something like this:
1
*** Payment event ***
2
[ { network: 'testnet',
3
transaction:
4
{ id: 1184244,
5
hash:
6
'5130a99f0810bfb4feef5360c18a5e70f86bfcc15de25d6f5a56321a7ca14cbe',
7
block_id: 3136969,
8
block_index: 0,
9
out_sum: 949155995,
10
fee: 168273,
11
deposit: 0,
12
size: 289,
13
invalid_before: null,
14
invalid_hereafter: 38824081,
15
valid_contract: true,
16
script_size: 0,
17
block: [Object] },
18
direction: 1,
19
utxo:
20
{ address:
21
'addr_test1qpmslzfze9fjgqnwauxqpscc5fvgr7wvmymn5t505vd5httchgg3vgms2ur8uwlpku2hvznsu4dayk4fl3ggn0sr3lgqtmfvcr',
22
direction: 1,
23
hash:
24
'5130a99f0810bfb4feef5360c18a5e70f86bfcc15de25d6f5a56321a7ca14cbe',
25
index: 0,
26
value: '10000000' } } ]
Copied!
You can also check the received event with the local Ngrok client http://localhost:4040/​
local Ngrok inspector

Webhook Signature and Security

If you want to make your webhooks extra secure, you can verify that they originated from Tangocrypto by generating an HMAC SHA-256 hash code using your Authentication Token and request body.

1. Find your Authentication Token

Navigate to the top right corner of your Notify page to copy your "Auth Token".
Auth token

2. Validate the signature received

Every outbound request will contain a hashed authentication signature in the header which is computed by concatenating your auth token and request body then generating a hash using the HMAC SHA256 hash algorithm.
In order to verify this signature came from Tangocrypto, you simply have to generate the HMAC SHA256 hash and compare it with the signature received. This procedure is commonly known as verifying the digital signature.

Example Request Header

1
Content-Type: application/json;
2
x-tangocrypto-signature: your-hashed-signature
Copied!

Example Signature Validation Function

JavaScript
Python
1
const crypto = require('crypto'); //import the crypto module (not related to us :) )
2
​
3
function isValidSignature(request) {
4
const token = '<your token goes here>';
5
const headers = request.headers;
6
const signature = headers['x-tangocrypto-signature'];
7
const body = request.body;
8
const hmac = crypto.createHmac('sha256', token) // Create a HMAC SHA256 hash using the auth token
9
hmac.update(JSON.stringify(body), 'utf8') // Update the token hash with the request body using utf8
10
const digest = hmac.digest('hex');
11
return (signature === digest); // If signature equals your computed hash, return true
12
}
Copied!
1
import hmac
2
import hashlib
3
import json
4
​
5
def isValidSignature(request):
6
token = '<your token goes here>';
7
headers = request['headers'];
8
signature = headers['x-tangocrypto-signature'];
9
body = request['body'];
10
string_body = json.dumps(body, separators=(',', ':'))
11
12
digest = hmac.new(
13
bytes(token, 'utf-8'),
14
msg=bytes(string_body, 'utf-8'),
15
digestmod=hashlib.sha256
16
).hexdigest()
17
18
return (signature == digest);
Copied!