> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borderless.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdrawal Webhooks

<Note>
  If you're just getting started, please check out our [quick start guide](/docs/quick-start-guide).
</Note>

## Transaction Creation

When a withdrawal transaction is created, a webhook notification will be sent to the configured webhook URL. This notification will contain the relevant transaction details for further processing or integration with your system. Webhook payload is below:

<CodeGroup>
  ```bash bash theme={null}
  {
    "type": "Transaction_Created",
    "organizationId": "clxt0xrqp0000gokerkq2mpdl",
    "timestamp": 1733495693232,
    "data": {
      "id": "cm4cuktc0000c5453lwolag7t",
      "type": "Withdrawal",
      "status": "Submitted",
      "source": {
        "asset": "USDT_ETHEREUM",
        "amount": "1",
        "fiatCurrency": null,
        "paymentMethod": null,
        "accountId": "cm46w78c40006ts9gkrx6r6jw",
        "accountName": "Main Account",
        "sender": null
      },
      "destination": {
        "asset": null,
        "amount": null,
        "fiatCurrency": "USD",
        "imad": null,
        "reference": null,
        "omad": null,
        "traceNumber": null,
        "externalAddress": null,
        "accountId": null,
        "accountName": null,
        "paymentInstructionId": "cm46w78c40006ts9gkrx6abcd"
      },
      "instructions": null,
      "createdAt": "2024-12-06T14:34:53.184Z",
      "txHash": [],
      "feeAmount": "0",
      "failureReason": null,
      "counterPartyIdentityId": "cm46w78c40006ts9gkrx6efgh",
      "virtualAccountId": null
    }
  }
  ```
</CodeGroup>

## Transaction state changes

Subsequent transaction processing updates and state changes will be communicated via webhook notifications to the configured webhook URL. Webhook payload remains as previous, please note its status change:

<CodeGroup>
  ```bash bash theme={null}
  {
    "type": "Transaction_Updated",
    "organizationId": "clxt0xrqp0000gokerkq2mpdl",
    "timestamp": 1733495695125,
    "data": {
      "id": "cm4cuktc0000c5453lwolag7t",
      "type": "Withdrawal",
      "status": "Verifying",
      "source": {
        "asset": "USDT_ETHEREUM",
        "amount": "1",
        "fiatCurrency": null,
        "paymentMethod": null,
        "accountId": "cm46w78c40006ts9gkrx6r6jw",
        "accountName": "Main Account",
        "sender": null
      },
      "destination": {
        "asset": null,
        "amount": null,
        "fiatCurrency": "USD",
        "imad": null,
        "reference": null,
        "omad": null,
        "traceNumber": null,
        "externalAddress": null,
        "accountId": null,
        "accountName": null,
        "paymentInstructionId": "cm46w78c40006ts9gkrx6abcd"
      },
      "instructions": null,
      "createdAt": "2024-12-06T14:34:53.184Z",
      "txHash": [],
      "feeAmount": "0",
      "failureReason": null,
      "counterPartyIdentityId": "cm46w78c40006ts9gkrx6efgh",
      "virtualAccountId": null
    }
  }
  ```
</CodeGroup>

The **txHash** field remains null until the transaction is executed on the underlying blockchain network. Once the transaction is processed, this field will be updated with the corresponding transaction hash.

## Transaction failure

In the case of a transaction failure, a webhook notification is sent to the configured webhook URL This notification contains detailed information about the transaction and the reason for its failure in .

<CodeGroup>
  ```bash bash theme={null}
  {
    "type": "Transaction_Updated",
    "organizationId": "clxt0xrqp0000gokerkq2mpdl",
    "timestamp": 1733495699167,
    "data": {
      "id": "cm4cuktc0000c5453lwolag7t",
      "type": "Withdrawal",
      "status": "Failed",
      "source": {
        "asset": "USDT_ETHEREUM",
        "amount": "1",
        "fiatCurrency": null,
        "paymentMethod": null,
        "accountId": "cm46w78c40006ts9gkrx6r6jw",
        "accountName": "Main Account",
        "sender": null
      },
      "destination": {
        "asset": null,
        "amount": null,
        "fiatCurrency": "USD",
        "imad": null,
        "reference": null,
        "omad": null,
        "traceNumber": null,
        "externalAddress": null,
        "accountId": null,
        "accountName": null,
        "paymentInstructionId": "cm46w78c40006ts9gkrx6abcd"
      },
      "instructions": null,
      "createdAt": "2024-12-06T14:34:53.184Z",
      "txHash": [],
      "feeAmount": "0",
      "failureReason": {
          "accountOwnerType": "is required"
      },
      "counterPartyIdentityId": "cm46w78c40006ts9gkrx6efgh",
      "virtualAccountId": null
    }
  }
  ```
</CodeGroup>

Please note: **failureReason** in the response above is sample only

## Payment instructions for an unsigned on-chain transaction to be executed using your own infrastructure

Webhook will contains payment instructions with two parts:

1. General Information: Details about the token, amount, and source/destination addresses:

<CodeGroup>
  ```bash bash theme={null}
  "instructions": {  
      "fromAddress": "0x123123",
      "toAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      "asset": "USDC_POLYGON",
      "amount": "12",
      "transaction": "SEE BELOW"
  ```
</CodeGroup>

2. Prepared Blockchain Transaction:

The transaction field depends on the blockchain. For **EVM-compatible blockchains** (non-native token):

<CodeGroup>
  ```bash bash theme={null}
  "instructions": {
      // General information. SEE ABOVE

      "transaction": {
          "to": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
          "data": "0xa9059cbb0000000000000000000000007d369e60b9dd8903006d09955d636630392e571800000000000000000000000000000000000000000000000000000000002dc6c0",
          "nonce": 19,
          "value": "0x00",
          "chainId": 137,
          "gasLimit": "0xf600",
          "gasPrice": "0x0689010ed9"
      }
  }
  ```
</CodeGroup>

This section for EVM-compatible blockchains (native token) will look like sample below:

<CodeGroup>
  ```bash bash theme={null}
  "instructions": {
      // General information. SEE ABOVE

      "transaction": {
          "to": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
          "nonce": 19,
          "value": "0x12",
          "chainId": 137,
          "gasLimit": "0xf600",
          "gasPrice": "0x0689010ed9"
      }
  }
  ```
</CodeGroup>

So you have two options:

1. Execute the already prepared raw transaction directly instructions.transaction
2. Use the provided data (fromAddress, toAddress, asset, and amount) to generate and execute your own transaction on the blockchain

<Info>
  If you have any questions, please don't hesitate to reach out to us via [email](mailto:support@borderless.xyz) or slack.
</Info>