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.

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.

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

Example Notification

Status: Paid

{
  "payoutId": 987654,
  "reference": "payout-2025-0001",
  "isoCountry": "CO",
  "created": "2025-10-14T10:30:00Z",
  "lastUpdate": "2025-10-14T10:32:10Z",
  "status": 1,
  "statusDescription": "Paid",
  "amount": {
    "value": 1000.00,
    "currency": "USD"
  },
  "localAmount": {
    "value": 4065000.00,
    "currency": "COP"
  },
  "exchangeRate": 4065,
  "payee": {
    "firstName": "María",
    "lastName": "González",
    "bankName": "Bancolombia",
    "accountNumber": "1234567890"
  },
  "description": "Freelancer payment - October"
}