🛩
How to Set Up Webhooks on BlockVision
Everything you need to know for using BlockVision Webhooks in your decentralized Ethereum app. Get notifications for mined and dropped transactions
Check out this step by step video tutorial:

What are Webhooks?

Webhooks are a way for users to receive notifications when events occur in an application. Instead of constantly polling the server to check if the state has changed, webhooks provide you with information as it becomes available, which is more efficient and beneficial for developers.
A webhook defines an event-triggered HTTP callback handler. It works by registering a URL to be notified when certain events occur. When a new event message is generated, the application will receive the event message sent by the server through the Webhook URL.

When to notify?

When the app you create has transaction status updated to mined or dropped, the webhook notification will be sent. So you can create a webhook to receive transaction state changes in real-time. If you haven't created the app yet, you need to create the app first. https://dashboard.blockvision.org/app is the link to create the app. We assume you have already created the app. Please see below about webhook content.

Types of Webhooks

Mined Transaction

The Mined Transaction Webhook is used to notify your app anytime a transaction sent through your API key gets successfully mined.
transaction object data structure:
  • app: your app name
  • network: the blockchain network, can be “Mainnet”,” Testnet”
  • webhookType: the type of webhook, only be “Mined_Transaction”,” Dropped_Transaction”
  • timestamp: current DateTime string
  • transaction: transaction object (same output as calling eth_getTransactionByHash)
Payload example:
{
"app":"blockvision eth",
"network":"Mainnet",
"webhookType":"Mined_Transaction",
"timestamp":"2022-03-20 14:22:53",
"transaction":{
"blockHash":"0x55103e01d8082a6bbbe2cce2c62d8425725a4c09dcc64b6b6299b57854281286",
"blockNumber":"0x10e82c4",
"from":"0xff6da3f7a8381e212148fb970354481741153d40",
"gas":"0x5208",
"hash":"0x9e5c339fe280312108e66ff782a6b6bb7397b0798cee35c6629485c47898a50a",
"input":"0x",
"nonce":"0x6",
"to":"0xff6da3f7a8381e212148fb970354481741153d40",
"transactionIndex":"0x8",
"value":"0x5af3107a4000",
"type":"0x0",
"v":"0xe6",
"r":"0x63489b2744576f15c18aa222e7215af1134ab30299c74323a04cec7b4820c749",
"s":"0xcadc240083be5980a25659ab1458410b30b8c528d8f26efadde722f5240432a"
}
}

Dropped Transactions

The Dropped Transactions Webhooks is used to notify your app anytime a transaction send through your API key gets dropped.
Payload example:
{
"app":"blockvision eth",
"network":"Mainnet",
"webhookType":"Dropped_Transaction",
"timestamp":"2022-03-20 14:22:53",
"transaction":{
"blockHash":"0x55103e01d8082a6bbbe2cce2c62d8425725a4c09dcc64b6b6299b57854281286",
"blockNumber":"0x10e82c4",
"from":"0xff6da3f7a8381e212148fb970354481741153d40",
"gas":"0x5208",
"hash":"0x9e5c339fe280312108e66ff782a6b6bb7397b0798cee35c6629485c47898a50a",
"input":"0x",
"nonce":"0x6",
"to":"0xff6da3f7a8381e212148fb970354481741153d40",
"transactionIndex":"0x8",
"value":"0x5af3107a4000",
"type":"0x0",
"v":"0xe6",
"r":"0x63489b2744576f15c18aa222e7215af1134ab30299c74323a04cec7b4820c749",
"s":"0xcadc240083be5980a25659ab1458410b30b8c528d8f26efadde722f5240432a"
}
}

How to create a webhook?

For a video version of this doc, check this out:
First go to the Webhook page and log in
Click the [Create Webhook] button to open the creation window
Fill in or select the following information:
  • Choose an app you want to create a webhook
  • Webhook URL(URL starting with HTTP or HTTPS protocol)
  • Click the [Test Webhook] button to check the URL is work
After filling in, click Confirm, and the Webhook is created successfully. Each type can create up to 50 records. You can view all webhooks in the My Webhook list.
When you don't need it, you can turn it off by turning off the switch.
When you exceed the quantity limit, you can delete some unimportant ones.
You can click the [Payload Format] in the upper right corner to view the data structure.

Webhook Signature and Security

If you want to make your webhooks extra secure, you can verify that they originated from BlockVision by generating an HMAC SHA-256 hash code using your unique webhook signing key.
  1. 1.
    Find your signing key
You can click the [Signing Key] and view the key.
2. Validate the signature received
Every outbound request will contain a hashed authentication signature in the header which is computed by concatenating your signing key and request body then generating a hash using the HMAC SHA256 hash algorithm.
To verify this signature came from BlockVision, you simply have to generate the HMAC SHA256 hash and compare it with the signature received from the header named X-BV-SIGN.
POST /yourWebhookServer/push HTTP/1.1
Content-Type: application/json;
X-BV-SIGN: your-hashed-signature
The signature rule is to splice your webhook URL & then splice the timestamp (obtained from the payload body) and then encrypt it with hmac_sha256 using the signing key.
This is just an example, the implementation method may be different in different languages.
JavaScript
Python
function isValidSignature(request) {
let webhookUrl = "https://www.myapp.com/webhookUrl";
let signingKey = 'signingKey provided by BlockVision on the Webhook setup page';
let headers = request.headers;
let signature = headers['X-BV-SIGN'];
let body = request.body;
let timestamp = body.timestamp;
let paramStr = webhookUrl + '&' + timestamp
let hmac = crypto.createHmac('sha256', signingKey) // Create a HMAC SHA256 hash using the signingKey
hmac.update(JSON.stringify(paramStr), 'utf8')
let digest = hmac.digest('hex');
return (signature === digest); // If signature equals your computed hash, return true
}
import hmac
import hashlib
import json
def isValidSignature(request):
webhookUrl = "https://www.myapp.com/webhookUrl";
signingKey = 'signingKey provided by BlockVision on the Webhook setup page';
headers = request['headers'];
signature = headers['X-BV-SIGN'];
timestamp = request['body']['timestamp'];
paramStr = webhookUrl + '&' + timestamp
digest = hmac.new(
bytes(signingKey, 'utf-8'),
msg=bytes(paramStr, 'utf-8'),
digestmod=hashlib.sha256
).hexdigest()
return signature == digest