Webhooks

Merchants can implement a webhook to receive notifications about the final status of their payouts.
This allows automatic reconciliation and status updates within your system once Bamboo completes the payout.

💡
Notifications are sent only for the following statuses: Held, Paid, Declined, and Rejected.

Supported Statuses

Status	Code	Description
`HELD`	`7`	The payout is under manual review by the Compliance team.
`PAID`	`1`	The payout has been successfully processed. This is a final status.
`DECLINED`	`8`	The payout was declined due to structural validation or Compliance rules.
`REJECTED`	`4`	The payout was rejected. Possible reasons include invalid bank account data or exceeded limits.

For a complete list of payout states, refer to the Payout Status guide.

Authentication and Signature

Each notification sent by Bamboo includes a digital signature in the request header.
The merchant must validate this signature to ensure the message’s authenticity and prevent tampering.

Property	Type	Description
Method	`POST`	All webhook notifications use the HTTP POST method.
Content-Type	`application/json`	The request body is formatted in JSON.
Authentication	Header signature	HMAC SHA-256 generated using the merchant’s private key.
Response	HTTP Status Code	`200 OK` confirms successful processing. Any other code triggers retries.

Signature validation example

var key = merchantSecretKey;
var receivedData = country + amount + currency + reference + payoutType + payoutId; // dateSent header
var expectedSignature = CryptoJS.HmacSHA256(receivedData, key).toString(CryptoJS.enc.Hex);

if (expectedSignature === receivedSignature)
  console.log("Signature is valid");
else
  console.log("Invalid signature");

⚠️
Always validate the signature using your private key before processing any notification.
Take the data from the body of the webhook message.

Webhook Service Specifications

The webhook must be an HTTP/REST service capable of receiving POST requests from Bamboo’s servers.

Field	Description
URL	Defined by the merchant.
API Type	Public
Method	POST
Response	HTTP Status Code (200 = received successfully)

Notification Parameters

Parameter	Type	Description
`payoutId`	`integer`	Internal ID of the payout generated by Bamboo.
`reference`	`string`	Unique identifier defined by the merchant during payout creation.
`isoCountry`	`string`	Country ISO code in format `ISO 3166-1 alpha-2`.
`created`	`datetime`	Date and time when the payout was requested.
`lastUpdate`	`datetime`	Date and time when the payout status was last updated.
`status`	`integer`	Current status code of the payout.
`statusDescription`	`string`	Description of the final payout status. See Payout Status.
`errorCode`	`string`	Internal error code if the payout failed. See Error Codes.
`errorDescription`	`string`	Description of the error if the payout failed.
`amount`	`object`	Amount and currency originally requested.
`localAmount`	`object`	Amount and currency converted to local value.
`exchangeRate`	`number`	Exchange rate applied to the payout.
`payee`	`object`	Information about the recipient or beneficiary.
`description`	`string`	Description or reason provided in the payout request.
`payoutType`	`integer`	Transfer type.

ℹ️
For company payouts, the payload includes companyName instead of firstName and lastName.

Example Notification

Status: Rejected

{
  "payoutId": 274898330574824832,
  "reference": "ARI-1963",
  "isoCountry": "AR",
  "created": "2026-01-28T13:47:49.5844134Z",
  "lastUpdate": "2026-01-28T14:56:03.9878851Z",
  "status": 4,
  "statusDescription": "Rejected",
  "errorCode": "902",
  "errorDescription": "Invalid bank account",
  "amount": {
    "value": 10,
    "isoCurrency": "USD"
  },
  "localAmount": {
    "value": 14751.94,
    "isoCurrency": "ARS"
  },
  "exchangeRate": 1505.3,
  "payee": {
    "firstName": "Ari",
    "lastName": "Carba",
    "email": "",
    "phone": "099999999",
    "address": "address",
    "location": {
      "city": "",
      "address": "address",
      "zipCode": ""
    },
    "document": {
      "number": "11111111111",
      "type": "CUIT"
    }
  },
  "description": "string",
  "payoutType": 2
}