Events

OpenXSwitch provides webhook notifications for various flows, including withdrawal, deposit, and internal transfers. Each flow consists of parent methods with specific sub-methods that represent the status or progress of the event. These webhooks ensure real-time updates to your application for key activities.

1. Withdrawal Event

Webhooks for the withdrawal flow notify you about the status of funds being withdrawn from a wallet.

Parent Method: withdraw
Sub-Methods:
- unconfirmed: Triggered when a withdrawal request is initiated but not yet processed.
- confirmed: Triggered when the withdrawal is successfully processed and funds are sent to the specified address.

Example Payload for Withdrawal:

{
  "requestId": "",
  "method": "withdraw.unconfirmed",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "withdraw.confirmed",
  "timestamp": "",
  "params": {
    .....
  }
}

2. Deposit Event

Webhooks for the deposit flow notifies you about incoming deposits and their status.

Parent Method: deposit
Sub-Methods:
- pending: Triggered when a deposit is initiated and is awaiting blockchain confirmation.
- updated: Triggered when the deposit progresses through intermediate confirmations(0,2...).
- success: Triggered when the deposit is fully confirmed and credited to the wallet.

Example Payload for Deposit:

{
  "requestId": "",
  "method": "deposit.pending",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "deposit.updated",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "deposit.success",
  "timestamp": "",
  "params": {
    .....
  }
}

3. Internal Transfer Event

Webhooks for internal transfers notify you about fund movements between wallets or accounts within the OpenXSwitch system.

Parent Method: internal\_transfer
Sub-Methods:
- completed: Triggered when the internal transfer is successfully processed.

Example Payload for Transfer:

{
  "requestId": "",
  "method": "internal_transfer.completed",
  "timestamp": "",
  "params": {
    .....
  }
}

4. Trade Event

Webhooks for trade events notify you about the status of trade-related transactions within the OpenXSwitch system.

Parent Method: trade
Sub-Methods:
- live: Triggered when a trade is created and actively ongoing.
- cancelled: Triggered when a trade is cancelled before completion.
- done: Triggered when a trade is fully executed.
- partly\_done: Triggered when a trade is partially executed but not yet completed.
- failed: Triggered when a trade fails due to an error or insufficient funds.

Example Payload for Trade:

{
  "requestId": "",
  "method": "trade.live",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "trade.partly_done",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "trade.done",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "trade.cancelled",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "trade.failed",
  "timestamp": "",
  "params": {
    .....
  }
}

5. Swap Event

Webhooks for swap events notify you about the status of swap-related transactions within the OpenXSwitch system.

Parent Method: swap
Sub-Methods:
- Awaiting Deposit: Triggered when a deposit is expected but not yet received.
- Confirming Deposit: Triggered when the deposit is detected and awaiting confirmation.
- Exchanging: Triggered when the swap is in progress.
- Sending: Triggered when the exchanged funds are being sent to the recipient.
- Complete: Triggered when the swap is successfully completed.
- Refund: Triggered when a refund is issued due to an issue.
- Failed: Triggered when the swap fails due to an error or insufficient funds.
- Volatility Protection: Triggered when the transaction is affected by high volatility safeguards.
- Action Request: Triggered when user action is required to proceed.
- Request Overdue: Triggered when a required action has not been completed within the expected time frame.

Example Payload for Swap:

{
  "requestId": "",
  "method": "swap.awaiting_deposit",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.confirming_deposit",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.exchanging",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.sending",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.complete",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.refund",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.failed",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.volatility_protection",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.action_request",
  "timestamp": "",
  "params": {
    .....
  }
}

{
  "requestId": "",
  "method": "swap.request_overdue",
  "timestamp": "",
  "params": {
    .....
  }
}

Other Webhook Parent Methods

offramp:
- Triggered for transactions that convert crypto assets to fiat.
- Sub-methods can include statuses like initiated, completed.
onramp:
- Triggered for transactions that convert fiat into crypto assets.
- Sub-methods can include statuses like initiated, completed.

Best Practices

Idempotent Processing: Ensure your webhook handlers are idempotent to avoid duplicate processing.
Acknowledgment: Always respond with a 2xx HTTP status code within 5 seconds to acknowledge receipt.
Security: Verify webhook payload signatures to ensure authenticity.