Webhook

Webhook setup for deposit notifications

Webhook is used for sending deposit notifications to your desired URL. You can setup the URL upon wallet creation and it will send a deposit notification request to your endpoint using your key and secret

The request includes 2 headers:

  • key: Same client key

  • secret: Same client secret

Once your server receives the request on your endpoint you need to check the request key and secret to check the validity of the request and make sure that this request is coming from Vault. (In more advanced scenarios HMAC-signature structure can be configured)

You can use webhook test on REST API interactive explorer on https://api.bitholla.com/docs to test the sample request sent to your server.

Webhook request expects 200 status response from your server.

Check the fields in is_confirmed and is_suspicious in the data you receive on your server. The webhook notifications are always sent when the deposit is confirmed. Often you receive the first webhook notification with status is_confirmed: false which is used to notify about an incoming deposit. In these cases do not assume the deposit is confirmed and wait for the second notification before you process it.

post
Webhook Test

https://api.bitholla.com/v1/vault/webhook/test
This endpoint allows you to test webhook endpoint with your own mock data to test the behavior and signed request sent to your server. Note that this is just a tester and the notifications will only be sent to your server upon actual deposits to your crypto wallet.
Request
Response
Request
Headers
key
required
string
User API key
secret
required
string
User API secret token
Body Parameters
is_testnet
optional
boolean
Specify whether or not the transaction was on the testnet. Default value: false
type
required
string
Transaction type. In this case it is always deposit.
height
optional
integer
blockchain height where transaction is added
currency
required
string
Currency name (btc, eth etc)
wallet_name
required
string
Wallet name the has the address which received a deposit
webhook
required
string
Your test URL (This field wont be used in the actual request from vault to your server)
txid
required
string
Transaction id on the blockchain
confirmation
required
integer
Number of confirmation a transaction has received in blockchain
is_confirmed
required
boolean
If the transaction has blockchain confirmation
is_suspicious
required
boolean
Specifies if a transaction is suspicious and is recommended for the client to check further
address
required
string
Crypto address that receives the deposit
amount
required
number
Deposit amount
Response
200: OK
{
"id": 1,
"name": "string",
"currency": "string",
"master": "string",
"version": 1,
"is_testnet": false,
"webhook": "string",
"created_at": "2019-11-06T02:22:09.117Z",
"updated_at": "2019-11-07T04:31:58.671Z",
"user_id": 1
}

Advance Signature

This structure is not used for normal wallets and is only applied for extra security upon client request. In the advance model, webhook deposit notification signs your request using your provided key and secret.

You are required to calculate the signature on your side and match it with the api-signature provided along with the api-nonce in the request header.

This is a sample code for signature you can refer to:

const secret = <your api-secret>;
const verb = 'POST';
const url = <your wallet webhook url>;
const data = <notification object data>;
const nonce = Date.now();
const stringData = JSON.stringify(data);
const signature = crypto
.createHmac('sha256', secret)
.update(verb + url + nonce + stringData)
.digest('hex');
console.log(signature)