Events

You may select which events you'd like to receive webhooks for in the Bitvora Console (opens in a new tab).

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"
  }
}