Webhooks
Brief guide to set up your notifications service.
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"
}
}
}
Updated 10 months ago