Webhook Event Schemas

Detailed payload schemas for all webhook events sent by WickiePay.

Crypto Events

Address Created

Event: crypto.address.created

Triggered when a new blockchain address is created.

{
  "event": "crypto.address.created",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "id": "addr-uuid",
    "address": "0x1234...abcd",
    "network": "ETHEREUM",
    "asset": "USDC",
    "assetPoolId": "pool-uuid",
    "status": "ACTIVE"
  }
}

Deposit Events

Deposit Status Change

Event: deposit.status_change

Triggered when a deposit status changes (detected, confirmed, completed).

{
  "event": "deposit.status_change",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "id": "tx-uuid",
    "type": "DEPOSIT",
    "status": "CONFIRMED",
    "previousStatus": "PENDING",
    "address": "0x1234...abcd",
    "network": "ETHEREUM",
    "asset": "USDC",
    "amount": 1000.00,
    "txHash": "0xabc...123",
    "confirmations": 12,
    "assetPoolId": "pool-uuid"
  }
}

Withdrawal Events

Withdrawal Status Change

Event: withdrawal.status_change

Triggered when a withdrawal status changes.

{
  "event": "withdrawal.status_change",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "id": "tx-uuid",
    "type": "WITHDRAWAL",
    "status": "COMPLETE",
    "previousStatus": "PROCESSING",
    "toAddress": "0xDEST...5678",
    "network": "ETHEREUM",
    "asset": "USDC",
    "amount": 500.00,
    "txHash": "0xdef...456",
    "fee": 2.50,
    "assetPoolId": "pool-uuid"
  }
}

Consolidation Events

Consolidation Status Change

Event: consolidation.status_change

Triggered when a consolidation operation status changes.

{
  "event": "consolidation.status_change",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "id": "consolidation-uuid",
    "status": "COMPLETE",
    "asset": "USDC",
    "amount": 5000.00,
    "sourceAddresses": ["0xA...", "0xB..."],
    "targetAddress": "0xC...",
    "assetPoolId": "pool-uuid"
  }
}

Trade Events

Conversion Created

Event: trade.conversion.created

{
  "event": "trade.conversion.created",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "id": "conversion-uuid",
    "fromCurrency": "USDC",
    "toCurrency": "EUR",
    "fromAmount": 10000.00,
    "toAmount": 9216.00,
    "rate": 0.9216,
    "status": "PENDING"
  }
}

Conversion State Changed

Event: trade.conversion.state_changed

{
  "event": "trade.conversion.state_changed",
  "timestamp": "2026-01-15T10:25:30Z",
  "data": {
    "id": "conversion-uuid",
    "status": "COMPLETE",
    "previousStatus": "PROCESSING",
    "fromCurrency": "USDC",
    "toCurrency": "EUR",
    "fromAmount": 10000.00,
    "toAmount": 9218.50,
    "rate": 0.92185
  }
}

Balance Events

Digital Balance Updated

Event: balance.updated

Triggered when any digital asset balance changes.

{
  "event": "balance.updated",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "assetPoolId": "pool-uuid",
    "asset": "USDC",
    "network": "ETHEREUM",
    "availableBalance": 15000.00,
    "pendingBalance": 500.00,
    "totalBalance": 15500.00,
    "changeAmount": 1000.00,
    "changeType": "DEPOSIT"
  }
}

Approval Events

Approval Request Status Changed

Event: approval.request.status_changed

{
  "event": "approval.request.status_changed",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "id": "approval-uuid",
    "status": "APPROVED",
    "previousStatus": "PENDING",
    "operationType": "WITHDRAWAL",
    "requiredVotes": 2,
    "currentVotes": 2,
    "requestedBy": "user-uuid"
  }
}

Approval Vote Required

Event: approval.vote_required

Triggered when a new approval request needs votes.

{
  "event": "approval.vote_required",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "id": "approval-uuid",
    "operationType": "WITHDRAWAL",
    "amount": 50000.00,
    "asset": "USDC",
    "requiredVotes": 2,
    "currentVotes": 0,
    "approvers": ["user-uuid-1", "user-uuid-2"]
  }
}

Audit Events

API Audit Event

Event: audit.api

Logged for all API calls.

{
  "event": "audit.api",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "method": "POST",
    "path": "/api/v1/pay/summary",
    "clientId": "client-uuid",
    "statusCode": 200,
    "ipAddress": "203.0.113.1",
    "userAgent": "WickiePay-Server/1.0"
  }
}

Event: audit.login

{
  "event": "audit.login",
  "timestamp": "2026-01-15T10:25:00Z",
  "data": {
    "userId": "user-uuid",
    "email": "user@company.com",
    "method": "API_KEY",
    "ipAddress": "203.0.113.1",
    "success": true
  }
}

Webhook Delivery

Property	Value
Method	POST
Content-Type	application/json
Timeout	30 seconds
Retries	3 attempts with exponential backoff
Signature	HMAC-SHA256 in `X-Webhook-Signature` header

All payloads include a top-level event string and timestamp (ISO 8601), plus a data object with event-specific fields.

Crypto Events​

Address Created​

Deposit Events​

Deposit Status Change​

Withdrawal Events​

Withdrawal Status Change​

Consolidation Events​

Consolidation Status Change​

Trade Events​

Conversion Created​

Conversion State Changed​

Balance Events​

Digital Balance Updated​

Approval Events​

Approval Request Status Changed​

Approval Vote Required​

Audit Events​

API Audit Event​

Authentication Login Event​

Webhook Delivery​