Webhook Events

Every Webhook request to your webhook URL comes with a payload, and this payload contains the details of the transaction for which you are being notified.

Webhook Payload Definitions

Transaction Event Definition

Field	Description	Type
`event`	The webhook event action that triggered the webhook	String
`data`	All information related to this specific webhook.	Object
`data.transaction`	All information related to the transaction is being carried out.	Object
`data.transaction.reference`	Basqet transaction reference	String
`data.transaction.merchant_name`	Basqet merchant name	String
`data.transaction.payment_currency`	Transaction currency id	String
`data.transaction.payment_currency_slug`	Transaction currency slug	String
`data.transaction.customer_email`	Your customer's email	String
`data.transaction.customer_name`	Your customer's name	String
`data.transaction.status`	Transaction status (`INITIATED`,`PENDING`,`ABANDONED`,`SUCCESSFUL`)	String
`data.transaction.payment_amount`	Payment amount (Amount User was to pay)	String
`data.transaction.amount_paid`	Amount Paid (Amount user sent to wallet address)	String
`data.transaction.description`	Transaction description / Description of payment	String
`data.transaction.is_live`	Merchant account status / Live or Sandbox transaction	Boolean / String
`data.transaction.created_at`	The date the transaction was created.	String

**Sample Transaction Event*

{
  "event": "payment.received",
  "data": {
    "transaction": {
      "reference": "bq_RkaUV0Zy3PGpQsT8c",
      "merchant_name": "Bar BQ Express",
      "payment_currency": 3,
      "payment_currency_name": "Bitcoin",
      "payment_currency_slug": "BTC",
      "status": "SUCCESSFUL",
      "customer_email": "[email protected]",
      "customer_name": "John Doe",
      "payment_amount": 1,
      "amount_paid": 1,
      "description": "Payment for Lamborghini",
      "is_live": false,
      "created_at": "2026-02-09T16:18:20.000Z",
      "meta": {}
    }
  }
}

Wallet Event Definition

Field	Description	Type
`event`	The webhook event action that triggered the webhook	String
`data`	All information related to this specific webhook	Object
`data.wallet`	All information related to the wallet that was updated	Object
`data.wallet.transaction_reference`	Reference of transaction that triggered wallet update	String
`data.wallet.amount`	Amount that was added to wallet	Number
`data.wallet.available_balance`	Balance on wallet	Number
`data.wallet.ledger_balance`	Ledger Balance of Wallet	Number
`data.wallet.currency`	Currency code of the wallet that was updated e.g USDC	String
`data.wallet.name`	Name of the wallet that was updated e.g USD Coin	String
`data.wallet.is_live`	A boolean flag indicating the environment: `true` for production and `false` for sandbox.	Boolean

Sample Wallet Event

{
  "event": "wallet.updated",
  "data": {
    "wallet": {
      "transaction_reference": "bq_RkaUV0Zy3PGpQsT8c",
      "amount": 10.1178,
      "available_balance": 6.8399,
      "ledger_balance": 0,
      "currency": "USDC",
      "name": "USD Coin",
      "type": "CRYPTO",
      "is_live": false
    }
  }
}

Events

Basqet dispatches the following webhook events to communicate updates on incoming transactions and wallet changes:

payment.received: Dispatched whenever a merchant receives payment.
payment.initiated: Dispatched when a payment has been initialized.
payment.pending: Dispatched after a payment has been initiated.
payment.abandoned: Dispatched when a transaction has been abandoned.
wallet.updated: Dispatched when a wallet is updated.

Retry Policy

Merchants can manually retry a webhook using the Retry Transaction Webhook API

Responding to a Webhook Request

It is important to respond to the requests with a 200 status code to acknowledge that you have received the requests. Basqet does not pay attention to any request parameters apart from the request status code.

Best Practices

It is recommended to do the following when receiving webhook notifications from us:

Keep track of all notifications received: It’s important to keep track of all notifications you’ve received. When a new notification is received proceed to check that this has not been processed before giving value. A retry of already processed notifications can happen if we do not get a 200 HTTP Status code from your notification URL, or if there was a request time out.
Acknowledge receipt of notifications with a 200 HTTP status code: It’s recommended you immediately acknowledge receipt of the notification by returning a 200 HTTP Status code before proceeding to perform other logics, failure to do so might result in a timeout which would trigger a retry of such notification.