Skip to main content

Events

You may select which events you'd like to receive webhooks for in the Bitvora Console.

All Event Types (values)

Transactions are either deposits or withdrawals.

Deposit Events

  • deposit.lightning.completed
  • deposit.lightning.failed
  • deposit.onchain.completed
  • deposit.onchain.failed
  • deposit.onchain.pending

Withdrawal Events

  • withdrawal.lightning.completed
  • withdrawal.lightning.failed
  • withdrawal.lightning.pending
  • withdrawal.onchain.completed
  • withdrawal.onchain.failed
  • withdrawal.onchain.pending

Validating the status

A deposit or withdrawal can only have 3 statuses: pending, settled, or failed.

You should only consider a deposit or withdrawal as successful if the status is settled.

Metadata

Metadata is an object that you send us when you initiate a bitcoin transaction, generally used to link our data with your internal data.

For example, if you are making a withdrawal on behalf of one of your users, you would usually pass us the user's internal ID. This ID would be stored in the metadata object.

This way, when we deliver the webhook, you can reference the internal ID and credit/debit your user accounts accordingly.

Example Webhook Payload

headers: {
"bitvora-signature": "hmac-sha256 of the payload and the webhook secret"
}

payload: {
"event": "deposit.lightning.completed",
"data": {
"amount_sats": 100,
"chain_tx_id": null,
"created_at": "2024-08-29T16:30:03.868147Z",
"fee_sats": 0.5,
"id": "1e16666d-6192-4ae0-abcc-f8c08622cd49",
"lightning_invoice_id": "2919bd2e-b27a-41bc-9588-42cf3ff86500",
"metadata": null,
"network_type": "signet",
"rail_type": "lightning",
"recipient": "lntbs1u1pndpg0cpp5w6mpazzt6m2787xcujue0at36sv06zed0juevdtjdgsgye2uqscqdqcgf5hgan0wfsjqjtwwehkjcm9cqzzsxqrrsssp5xmaw5phx8f228uk4wy4fdft6q9xh3mlq5u2sudzk5kggc27ydypq9qxpqysgq0arjdtpwgq5n79kjq3z3mnzvkm2vy33h8fs8pkx38p9fwtuq9x9zcm6sgz9h3h4z626yt50l8g5yhytl4xq6rjcp8cf6rlk7nx9gfespqv867f",
"status": "settled",
"updated_at": "2024-08-29T16:30:03.868147Z"
}
}