Webhooks
Learn how to listen for transactions that happen on your account
Webhooks
A webhook is a URL on your server where we send payloads for transaction events. For example, if you implement webhooks, we will immediately notify your server with a btc.lightning.received.success
event once a lightning payment is received.
Whenever you receive a webhook notification from us, return a 200 OK
to avoid resending the same event again from our server.
Events
Transactions sent to your webhook URL have event types that provide more information about a transaction. It says what kind of transaction, sent or received, and the status of the transaction.
Here are the different event types:
Event Type | Description |
---|---|
| Successfully received payment via lightning |
| Lightning payment sent successfully |
| Failed to send a lightning payment |
| Successfully received a bitcoin payment onchain |
| Successfully sent a payment onchain |
| Failed to make an onchain payment |
| Debit Transactions on Virtual Cards |
| Reversed Transactions on Debit Card |
| Checkout payment paid but incompleted |
| Checkout payment completed. |
Verifying Events
It is necessary to verify that these events come from Bitnob to avoid creating transactions due to a fraudulent event.
To verify events, validate the x-bitnob-signature
header sent with the event. The HMAC SHA512 signature is the event payload signed with your secret key
.
const crypto = require('crypto');
const webhookSecret = process.env.BITNOB_WEBHOOK_SECRET;
// Using Express
app.post("/webhook_url", function(req, res) {
//validate event
const hash = crypto.createHmac('sha512', webhookSecret).update(JSON.stringify(req.body)).digest('hex');
if (hash == req.headers['x-bitnob-signature']) {
// Retrieve the request's body
const event = req.body;
// Do something with event
}
res.send(200);
});
import hmac
from hashlib import sha512
def webhook_verification(request):
secret = os.environ.get("BITNOB_WEBHOOK_SECRET")
signature = request.headers.get('x-bitnob-signature')
computed_sig = hmac.new(
key=webhook_secret.encode("utf-8"), msg=request.body, digestmod=sha512
).hexdigest()
#Bitnob generated events will return True
return signature == computed_sig
Notification Retries
When posting notifications, we expect to receive a 200 response code from you. If the response code is not 200, we will retry the notification every 30 minutes for up to 4 days.
This way, whenever you experience downtime on your end, your updates will still be sent.
Don't rely on webhooks entirely
We recommend that you set up a service to always query transaction statuses in the events webhooks keep failing.
Testing Webhooks
Since notifications must always be available in a publicly accessible URL, you are likely to run into issues while starting to build your application in a local environment. You can easily go around this by using a tool like ngrok
https://ngrok.com/.
Create a tunnel, update the new webhook URL setting on your dashboard. Only do this in your test environment in order to avoid leaking data to the public
Updated about 2 months ago