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

# Webhook Events

> Complete list of webhook events

## Deposit Events

### deposit.completed

Fired when a deposit is completed successfully.

#### Crypto Deposit

```json theme={null}
{
  "event": "deposit.completed",
  "eventId": "evt_abc123",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    "transactionId": "txn_001",
    "customerId": "cus_123",
    "sender": {
      "address": "0x123...",
      "chain": "Ethereum"
    },
    "recipient": {
      "address": "0x456...",
      "chain": "Ethereum"
    },
    "amount": 1000000,
    "currency": "USDT",
    "reference": "dep-20240115-001",
    "status": "completed",
    "transactionType": "deposit",
    "blockchain": "Ethereum",
    "transactionHash": "0x789...",
    "explorer_link": "https://etherscan.io/tx/0x789...",
    "timestamp": "2024-01-15T10:30:40Z"
  }
}
```

#### Fiat Deposit

```json theme={null}
{
  "event": "deposit.completed",
  "eventId": "evt_def456",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "transactionId": "txn_002",
    "customerId": "cus_456",
    "sender": {
      "accountName": "John Doe",
      "accountNumber": "0987654321",
      "bankName": "GTBank"
    },
    "recipient": {
      "accountName": "Jane Smith",
      "accountNumber": "0123456789",
      "bankName": "GTBank"
    },
    "amount": 50000,
    "currency": "NGN",
    "fee": 500,
    "reference": "dep-20240115-002",
    "status": "completed",
    "transactionType": "deposit",
    "notes": "Bank transfer deposit",
    "timestamp": "2024-01-15T11:00:00Z"
  }
}
```

## Withdrawal Events

### withdrawal.completed

Fired when a withdrawal is completed successfully.

```json theme={null}
{
  "event": "withdrawal.completed",
  "eventId": "evt_xyz789",
  "timestamp": "2024-01-15T11:45:23Z",
  "data": {
    "transactionId": "txn_003",
    "customerId": "cus_789",
    "recipient": {
      "accountName": "Jane Smith",
      "accountNumber": "0123456789",
      "bankName": "GTBank"
    },
    "amount": 25000,
    "currency": "NGN",
    "reference": "wth-20240115-001",
    "status": "completed",
    "transactionType": "withdrawal",
    "timestamp": "2024-01-15T11:45:20Z"
  }
}
```

### withdrawal.failed

Fired when a withdrawal fails.

```json theme={null}
{
  "event": "withdrawal.failed",
  "eventId": "evt_xyz789",
  "timestamp": "2024-01-15T11:45:23Z",
  "data": {
    "transactionId": "txn_003",
    "customerId": "cus_789",
    "recipient": {
      "accountName": "Jane Smith",
      "accountNumber": "0123456789",
      "bankName": "GTBank"
    },
    "amount": 25000,
    "currency": "NGN",
    "reference": "wth-20240115-001",
    "status": "failed",
    "transactionType": "withdrawal",
    "timestamp": "2024-01-15T11:45:20Z"
  }
}
```

## Transfer Events

### transfer.completed

Fired when a transfer is completed successfully.

```json theme={null}
{
  "event": "transfer.completed",
  "eventId": "evt_transfer1",
  "timestamp": "2024-01-15T12:30:00Z",
  "data": {
    "transactionId": "txn_004",
    "customerId": "cus_123",
    "sender": {
      "address": "0x123...",
      "chain": "Ethereum"
    },
    "recipient": {
      "address": "0x456...",
      "chain": "Ethereum"
    },
    "amount": 500000,
    "currency": "USDT",
    "reference": "trf-20240115-001",
    "status": "completed",
    "transactionType": "transfer",
    "blockchain": "Ethereum",
    "transactionHash": "0xabc...",
    "timestamp": "2024-01-15T12:30:00Z"
  }
}
```

### transfer.failed

Fired when a transfer fails.

```json theme={null}
{
  "event": "transfer.failed",
  "eventId": "evt_transfer2",
  "timestamp": "2024-01-15T13:15:00Z",
  "data": {
    "transactionId": "txn_005",
    "customerId": "cus_456",
    "sender": {
      "address": "0x789...",
      "chain": "Ethereum"
    },
    "recipient": {
      "address": "0xabc...",
      "chain": "Ethereum"
    },
    "amount": 300000,
    "currency": "USDT",
    "reference": "trf-20240115-002",
    "status": "failed",
    "transactionType": "transfer",
    "blockchain": "Ethereum",
    "transactionHash": "0xdef...",
    "timestamp": "2024-01-15T13:15:00Z"
  }
}
```

## Wallet Events

### wallet.balance.updated

Fired when a wallet balance is updated.

```json theme={null}
{
  "event": "wallet.balance.updated",
  "eventId": "evt_balance1",
  "timestamp": "2024-01-15T14:00:00Z",
  "data": {
    "fromAccount": {
      "accountNumber": "0123456789",
      "accountName": "Main Wallet",
      "bankName": "GTBank"
    },
    "toAccount": {
      "accountNumber": "0987654321",
      "accountName": "Savings Wallet",
      "bankName": "GTBank",
    },
    "amount": 25000,
    "currency": "NGN",
    "reference": "bal-20240115-001",
    "type": "withdrawal / deposit",
    "customerId": "cus_123",
    "narration": "Transfer between accounts",
    "timestamp": "2024-01-15T14:00:00Z"
  }
}
```

## Example Handler

```javascript theme={null}
app.post('/webhooks/fossapay', async (req, res) => {
  const { event, data } = req.body;

  res.status(200).send('OK');

  switch (event) {
    case 'deposit.completed':
      await handleDepositCompleted(data);
      break;

    case 'withdrawal.completed':
      await handleWithdrawalCompleted(data);
      break;

    case 'transfer.completed':
      await handleTransferCompleted(data);
      break;

    case 'transfer.failed':
      await handleTransferFailed(data);
      break;

    case 'wallet.balance.updated':
      await handleWalletBalanceUpdated(data);
      break;

    default:
      console.log('Unhandled event:', event);
  }
});
```