Webhooks

Bitso's Withdrawal and Funding Services provide webhooks to send real-time status data about withdrawal and funding events in your account.

To consume the webhook, set up and register with Bitso a callback URL where the webhook will deliver automatic updates on pending transactions. When a status change for supported events occurs, the webhook sends a notification via an HTTP POST method with the corresponding payload, documented below.

📘
Not Possible to Select Events
You cannot choose a specific event type to subscribe to. If you set up a callback URL, then a notification is sent for each supported event.

After the URL receives the update, you must store it and process it later. Callback URLs that take more than five seconds to respond time out.

URL Registration

To register your callback URL, make the following HTTP call with the corresponding body parameter:

POST https://api.bitso.com/api/v3/webhooks/

Body Parameters

callback_url: Specifies the URL that receives the status data the service sends when a withdrawal or deposit status change occurs in your account.

A successful registration sends back the following response body:

{
    "success": true,
    "payload": "Successfully registered URL: <callback_url>"
}

The registered URL must be accessible from the public web so that the webhooks can post the updates. Then, consider ways to secure the connection. You can request to your account manager the IP addresses sending the information for you to include them in an allowlist.

Funding Payload

If you register a callback URL, then when a deposit occurs, the webhook posts a JSON object that includes the following fields:

Field Name	Description	Type	Units
`amount`	The number of funds deposited.	String	Currency
`asset`	The digital asset in a network. In most cases, it is the same as `currency`.	String
`created_at`	The date and time when the service created the funding.	String	ISO 8601 timestamp
`currency`	The currency of the funded amount.	String
`details`	The specific funding details, the fields included vary depending on the funding method.	JSON object
`event`	The type of event reported. Possible values: Funding and Withdrawal.	String
`fid`	The funding's unique identifier.	String
`integration`	The specific integration that enables Bitso to connect to the given network.	String
`method`	The method used for this funding, such as praxis, pixbtg, btc, eth, and the like.	String
`method_name`	The method's long name	String
`network`	The payment network through which the deposit is processed.	String
`protocol`	A specific mechanism, protocol, or standard used in a network.	String
`status`	The funding's status. Possible values: Pending, Complete, and Failed.	String

The following shows a sample of the payload the service sends to the callback URL when a deposit is made into your account:

{
   "event":"funding",
   "payload":{
      "fid":"037c4c00e17c592fc7b6d9bad2261be8",
      "status":"complete",
      "created_at":"2023-05-17T23:12:00+00:00",
      "currency":"mxn",
      "method":"praxis",
      "method_name":"SPEI Transfer",
      "amount":"100.00",
      "asset":"mxn",
      "network":"spei",
      "protocol":"clabe",
      "integration":"praxis",
      "details":{
         "sender_name":"DARTH VADER",
         "sender_clabe":"*****0606032******",
         "sender_bank":40329,
         "clave":885364,
         "clave_rastreo":"2023051740014BMOV0000495448940",
         "numeric_reference":"2043562",
         "concepto":"PRUEBA DEPOSITO",
         "cep_link":""
      }
   }
}

Withdrawal Payload

If you register a callback URL, then when a withdrawal occurs, the webhook posts a JSON object that includes the following fields:

Field Name	Description	Type	Units
`amount`	The number of funds withdrawn.	String	Currency
`asset`	The digital asset in a network. In most cases, it is the same as `currency`.	String
`created_at`	The date and time when the service created the withdrawal.	String	ISO 8601 timestamp
`currency`	The currency of the withdrawn amount.	String
`details`	The specific withdrawal details, the fields included vary depending on the withdrawal method.	JSON object
`event`	The type of event reported. Possible values: funding and withdrawal.	String
`integration`	The specific integration that enables Bitso to connect to the given network.	String
`method`	The method used for this withdrawal, such as praxis, pixbtg, btc, eth, and the like.	String
`method_name`	The method's long name	String
`network`	The payment network through which the deposit is processed.	String
`protocol`	A specific mechanism, protocol, or standard used in a network.	String
`status`	The withdrawal's status. Possible values: pending, processing, complete, and failed.	String
`wid`	The withdrawal's unique identifier.	String

The following shows a sample of the payload the service sends to the callback URL when a withdrawal is made from your account:

{
   "event":"withdrawal",
   "payload":{
      "wid":"p4u8d7f0768ee91d3b33bee6483132i8",
      "status":"complete",
      "created_at":"2017-07-09T19:22:38+00:00",
      "currency":"xrp",
      "method":"rp",
      "method_name":"Ripple",
      "amount":"57",
      "asset":"xrp",
      "network":"rp",
      "protocol":"ripple",
      "integration":"rippled",
      "details":{
         "address":"*******LK5R5Am25ArfXFmqg**********",
         "destination_tag":"64136557",
         "ripple_transaction_hash":"33EA42FC7A06F062A7B843AF4DC7C0AB00D6644DFDF4C5D354A87C035813D321"
      }
   }
}

📘Not Possible to Select Events

URL Registration

Funding Payload

Withdrawal Payload

📘
Not Possible to Select Events