Information about new deposits are sent as POST requests to a configured url. The mnsig backend will retry it in case your server does not respond with status 200 or takes too long to handle it. If your system does a lot of custom processing with the received data, it's recommended to queue that and quickly send back any response with status 200.
mnsig encrypts the data transmitted using libsodium. To decrypt the data received you need the mnsig webhook public key for your instance.
In order to get mnsig to setup webhooks for you, the first step is to create a keypair used specifically for this (example in Python):
# If it's the first time using this, install the libsodium wrapper:
# pip install PyNaCl
import binascii
from nacl.public import PrivateKey
# Keep this secret on your server, it's necessary when attempting to read the webhooks sent to you.
secret = PrivateKey.generate()
secret_hex = binascii.hexlify(secret.encode()) # Store this result somewhere in order to reuse it.
# Share the corresponding public key
public_key_hex = binascii.hexlify(secret.public_key.encode())
print public_key_hex
When receiving webhooks you need to:
import json
import binascii
from nacl.public import PrivateKey, PublicKey, Box
server_public_key_hex = YOUR_MNSIG_INSTANCE_WEBHOOK_KEY
server_public_key = PublicKey(binascii.unhexlify(test_server_hex))
my_secret_hex = SECRET_HEX_GENERATED_ABOVE
my_secret = PrivateKey(binascii.unhexlify(my_secret_hex))
box = Box(my_secret, server_publickey)
raw = box.decrypt(binascii.unhexlify(encrypted_data))
data = json.loads(raw) # This is the data you were looking for.
Example of a webhook POST:
{
"raw": "0aa489b61443d02006f92071b032f3b7ddde69d85bdf4b496993d8bfdf245dc948db089bc0799c4c1b5e43518f0770f03bb6f166a5c52240e896e738a7a89a5e44cca6fdd563b5d2b2e4716b37f726603dca323d74387f4a91d197cfd56fb0501b47cfb551becf364058094094efbcc2d4bb12929eec0a158a99286d2122aa280291ad0e511a4b9b8415d1a2a5c1e5fbe37bea5aee792633f861c4452a766506e9c98b64f9afcd98060b424b257415ce942cb618067a5a403405617524f4fb063ae669f61bf56330f08500916ca013b8bb447336be64fd85fa9b84054fdbb070c0cf207f2118e57adafe8ad1126bad911ca86d138e8323dcfe35b3f19fe80d8aa7e9f1f19180ccaeb24c366b9a27b854bb961e4816ca555ed3ad3bf65f362404c22c26973eafd5b0f9568e6269b6bd23260febcb695f68f0f2a9e98d5e18a325d0d24eec0ca79fc59fceba7f51d40352c95ad0fe4b8eb4df20b67e909bdb4a5a0b01a3468396824976d3f0cf235a2636b2eea57182fa40406f0550069a909c577463184e542278a890d9faa0376117de25c2395f212fb84d946ded2626d578e5a86311eb1a17475fbf4d3805bd6a7c107c972967a89b668e14d79f79d12e79"
}
Decrypted data:
{
"proposal_id": null,
"complete_date": "2018-01-16T20:01:40.319434",
"bestblock_height": 1259257,
"txid": "220da9744251251dfa3b7b7eadadaff8922c2c7a8ebaab0adb91f73096901d6e",
"note": null,
"amount": 130000000,
"asset": "testbitcoin_segwit",
"tx_out": [],
"blockheight": null,
"tx_in": [
{
"amount": 130000000,
"description": {
"vout": 0
},
"address": "2NBhooKjSNibfn3CV7M7jLRXHa1Ytyvoh9z"
}
],
"external_id": null
}
mnsig will send at least another webhook POST after the transaction gets confirmed, in which case the blockheight key won't be null. For deposits, the keys proposal_id, note, and external_id are always null and tx_out is always an empty list. The asset key the wallet type for this deposit.
Note that the entries in the tx_in key always use amounts as integers, in this example the address 2NBhooKjSNibfn3CV7M7jLRXHa1Ytyvoh9z received 1.3 testnet BTC.
Example using PHP:
* Install this extension https://github.com/jedisct1/libsodium-php before continuing
<?php
if (!extension_loaded("sodium")) print "install and enable php libsodium extension";
$server_public_key_hex = '<server public key in hex>';
$server_public_key = sodium_hex2bin($server_public_key_hex);
$my_secret_hex = '<your secret key in hex>';
$my_secret = sodium_hex2bin($my_secret_hex);
$box = sodium_crypto_box_keypair_from_secretkey_and_publickey($my_secret, $server_public_key);
$encrypted_data = sodium_hex2bin( '0aa489b61443d02006f92071b032f3b7ddde69d85bdf4b496993d8bfdf245dc948db089bc0799c4c1b5e43518f0770f03bb6f166a5c52240e896e738a7a89a5e44cca6fdd563b5d2b2e4716b37f726603dca323d74387f4a91d197cfd56fb0501b47cfb551becf364058094094efbcc2d4bb12929eec0a158a99286d2122aa280291ad0e511a4b9b8415d1a2a5c1e5fbe37bea5aee792633f861c4452a766506e9c98b64f9afcd98060b424b257415ce942cb618067a5a403405617524f4fb063ae669f61bf56330f08500916ca013b8bb447336be64fd85fa9b84054fdbb070c0cf207f2118e57adafe8ad1126bad911ca86d138e8323dcfe35b3f19fe80d8aa7e9f1f19180ccaeb24c366b9a27b854bb961e4816ca555ed3ad3bf65f362404c22c26973eafd5b0f9568e6269b6bd23260febcb695f68f0f2a9e98d5e18a325d0d24eec0ca79fc59fceba7f51d40352c95ad0fe4b8eb4df20b67e909bdb4a5a0b01a3468396824976d3f0cf235a2636b2eea57182fa40406f0550069a909c577463184e542278a890d9faa0376117de25c2395f212fb84d946ded2626d578e5a86311eb1a17475fbf4d3805bd6a7c107c972967a89b668e14d79f79d12e79'
);
$nonce = mb_substr($encrypted_data, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, '8bit');
$ciphertext = mb_substr($encrypted_data, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, null, '8bit');
$raw = sodium_crypto_box_open($ciphertext, $nonce, $box);
var_dump($raw);
// Decode the JSON string:
//$data = json_decode($raw);
//var_dump($data);
?>
no comments
sign in to comment