Events

Overview

StableStack sends webhook events for transaction status changes across wallet deposits, withdrawals, and payouts. Each event includes a signed payload for verification and the complete transaction details.

Event Types

Wallet Events

wallet.transaction.inbound

Description: Triggered when a deposit/inbound transaction completes successfully. Triggered When:

User receives funds via Circle wallet deposit
Transaction status changes to COMPLETED
Funds are reflected in user’s wallet

Payload Example:

{
  "id": "evt_a0b8f4cc-95c4-4c74-9b18-050813546eb5",
  "timestamp": 1778538982206,
  "event_type": "wallet.transaction.inbound",
  "signature": "t=1778538982206,s=a43187f66dff73d9681a4ef43c5c93349d95fc10b6dc0482ec65e39b59564a83",
  "data": {
    "id": "dd1aebfd-acec-4367-a8dd-bdecea396753",
    "user_id": "318325f3-e612-4c57-8ce9-edfcbdcce1f3",
    "transaction_type": "DEPOSIT",
    "transaction_mode": "CREDIT",
    "amount": "20.00000000",
    "asset_code": "USDC",
    "network": "polygon",
    "status": "COMPLETED",
    "balance": "40.00000000",
    "transaction_id": "DCVDZZPVFC",
    "crypto_transaction_id": "0xda988304ee4506e9d8db67f2c90b7cb91aaf93457af6e9c05b9f377241764ca5",
    "reference_id": "e8ca80e3-10b2-5eab-a66b-c9edce037871",
    "sender_user": {
      "first_name": null,
      "last_name": null,
      "businessName": null,
      "role": null
    },
    "sender_wallet_details": {
      "address": null,
      "network": null,
      "currency": null,
      "bank_code": null,
      "bank_name": null,
      "account_number": null
    },
    "receiver_user": {
      "first_name": null,
      "last_name": null,
      "businessName": "ten demo ltd",
      "role": "merchant"
    },
    "receiver_wallet_details": {
      "address": "0x80fc73f856968ff4035ed239f82a962e50b1bae3",
      "network": "polygon",
      "currency": "USDC",
      "country": null,
      "bank_code": null,
      "bank_name": null,
      "account_number": null
    },
    "created_at": "2026-05-11T22:36:19.000Z",
    "updated_at": "2026-05-11T22:36:19.000Z"
  }
}

Important Fields:

`amount`: Transaction amount (string, decimal)
`asset_code`: Asset code (USDC, etc.)
`network`: Blockchain network (polygon, ethereum, etc.)
`crypto_transaction_id`: On-chain transaction hash
`status`: Always COMPLETED for this event
`balance`: User’s wallet balance after transaction
`sender_user`: Nested object with sender identity details
`receiver_user`: Nested object with receiver identity details
`receiver_wallet_details`: Wallet address and network info

wallet.transaction.outbound

Description: Triggered when a withdrawal/outbound transaction completes or updates. Triggered When:

User initiates a withdrawal via Circle wallet
Transaction reaches CONFIRMED or COMPLETE state
Transaction fails with FAILED status

Payload Example:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440002",
  "timestamp": 1715420500000,
  "event_type": "wallet.transaction.outbound",
  "signature": "t=1715420500000,s=bcde2345fghi6789jklm0123nopq4567...",
  "data": {
    "id": "txn_550e8400-e29b-41d4-a716-446655440003",
    "user_id": "user_123",
    "transaction_type": "WITHDRAWAL",
    "transaction_mode": "DEBIT",
    "amount": "500.00",
    "asset_code": "USDC",
    "network": "matic",
    "status": "COMPLETED",
    "balance": "500.00",
    "transaction_id": "WTHD123456",
    "crypto_transaction_id": "0x9876543210fedcba",
    "reference_id": "ref_withdrawal_001",
    "sender_user": {
      "first_name": "John",
      "last_name": "Doe",
      "businessName": null,
      "role": null
    },
    "sender_wallet_details": {
      "address": "0x1111111111111111111111111111111111111111",
      "network": "matic",
      "currency": "USDC",
      "bank_code": null,
      "bank_name": null,
      "account_number": null
    },
    "receiver_user": {
      "first_name": null,
      "last_name": null,
      "businessName": null,
      "role": null
    },
    "receiver_wallet_details": {
      "address": "0x2222222222222222222222222222222222222222",
      "network": "matic",
      "currency": "USDC",
      "country": null,
      "bank_code": null,
      "bank_name": null,
      "account_number": null
    },
    "created_at": "2025-05-11T10:30:00Z",
    "updated_at": "2025-05-11T10:35:00Z"
  }
}

Important Fields:

`status`: COMPLETED or FAILED
`crypto_transaction_id`: On-chain transaction hash
`sender_wallet_details`: Originating wallet info
`receiver_wallet_details`: Destination wallet info

Payout Events

payout.initiated

Description: Triggered when a payout request is initiated and confirmed. Triggered When:

User initiates a fiat payout (ZAR, NGN, USD, etc.)
Transaction enters PROCESSING status

Payload Example:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440004",
  "timestamp": 1715420600000,
  "event_type": "payout.initiated",
  "signature": "t=1715420600000,s=cdef3456ghij7890klmn1234opqr5678...",
  "data": {
    "id": "txn_550e8400-e29b-41d4-a716-446655440005",
    "user_id": "user_123",
    "transaction_type": "PAYOUT",
    "amount": "10000.00",
    "asset_code": "ZAR",
    "status": "PROCESSING",
    "reference_id": "FW-20250511-001234",
    "transaction_id": "PAYOUT12345",
    "recipient_currency": "ZAR",
    "bank_name": "ABSA Bank",
    "bank_account": "9876543210",
    "withdrawal_recipient_name": "John Doe",
    "sender_user": {
      "first_name": "Merchant",
      "last_name": "Account",
      "businessName": null,
      "role": "merchant"
    },
    "sender_wallet_details": {
      "address": null,
      "network": null,
      "currency": "ZAR",
      "bank_code": null,
      "bank_name": null,
      "account_number": null
    },
    "receiver_user": {
      "first_name": "John",
      "last_name": "Doe",
      "businessName": null,
      "role": null
    },
    "receiver_wallet_details": {
      "address": null,
      "network": null,
      "currency": "ZAR",
      "country": null,
      "bank_code": "123456",
      "bank_name": "ABSA Bank",
      "account_number": "9876543210"
    },
    "created_at": "2025-05-11T10:40:00Z",
    "updated_at": "2025-05-11T10:42:00Z"
  }
}

Important Fields:

`recipient_currency`: Target fiat currency (ZAR, NGN, USD, etc.)
`bank_name`: Receiving bank for the payout
`bank_account`: Bank account number (masked where possible)
`reference_id`: transaction reference

payout.processing

Description: Triggered when a payout is actively being processed. Triggered When:

Payout passes initial validation
Funds are being transferred to the recipient bank
Processing has started

Payload Example:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440006",
  "timestamp": 1715420700000,
  "event_type": "payout.processing",
  "signature": "t=1715420700000,s=defg4567hijk8901lmno2345pqrs6789...",
  "data": {
    "id": "txn_550e8400-e29b-41d4-a716-446655440005",
    "user_id": "user_123",
    "transaction_type": "PAYOUT",
    "amount": "10000.00",
    "asset_code": "ZAR",
    "status": "PROCESSING",
    "reference_id": "FW-20250511-001234",
    "transaction_id": "PAYOUT12345",
    "recipient_currency": "ZAR",
    "bank_name": "ABSA Bank",
    "bank_account": "9876543210",
    "withdrawal_recipient_name": "John Doe",
    "receiver_user": {
      "first_name": "John",
      "last_name": "Doe",
      "businessName": null,
      "role": null
    },
    "receiver_wallet_details": {
      "address": null,
      "network": null,
      "currency": "ZAR",
      "country": null,
      "bank_code": "123456",
      "bank_name": "ABSA Bank",
      "account_number": "9876543210"
    },
    "created_at": "2025-05-11T10:40:00Z",
    "updated_at": "2025-05-11T10:45:00Z"
  }
}

Important Fields:

`recipient_currency`: Target fiat currency (ZAR, NGN, USD, etc.)
`bank_name`: Receiving bank for the payout
`bank_account`: Bank account number
`withdrawal_recipient_name`: Recipient name at receiving bank
`reference_id`: transaction reference

payout.completed

Description: Triggered when a payout reaches the recipient’s bank account successfully. Triggered When:

Funds are confirmed received at destination bank
confirms successful completion
Transaction status changes to COMPLETED

Payload Example:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440007",
  "timestamp": 1715507100000,
  "event_type": "payout.completed",
  "signature": "t=1715507100000,s=efgh5678ijkl9012mnop3456qrst7890...",
  "data": {
    "id": "txn_550e8400-e29b-41d4-a716-446655440005",
    "user_id": "user_123",
    "transaction_type": "PAYOUT",
    "amount": "10000.00",
    "asset_code": "ZAR",
    "status": "COMPLETED",
    "reference_id": "FW-20250511-001234",
    "transaction_id": "PAYOUT12345",
    "recipient_currency": "ZAR",
    "bank_name": "ABSA Bank",
    "bank_account": "9876543210",
    "withdrawal_recipient_name": "John Doe",
    "receiver_user": {
      "first_name": "John",
      "last_name": "Doe",
      "businessName": null,
      "role": null
    },
    "receiver_wallet_details": {
      "address": null,
      "network": null,
      "currency": "ZAR",
      "country": null,
      "bank_code": "123456",
      "bank_name": "ABSA Bank",
      "account_number": "9876543210"
    },
    "created_at": "2025-05-11T10:40:00Z",
    "updated_at": "2025-05-12T10:05:00Z"
  }
}

Important Fields:

`status`: Always COMPLETED for this event
`reference_id`: Use for tracking
`bank_account`: Receiving bank account
`withdrawal_recipient_name`: Recipient name at receiving bank

payout.failed

Description: Triggered when a payout fails at any stage. Triggered When:

Bank rejects the transfer
Insufficient funds or invalid account details
Transaction status changes to FAILED

Payload Example:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440008",
  "timestamp": 1715507200000,
  "event_type": "payout.failed",
  "signature": "t=1715507200000,s=fghi6789jklm0123nopq4567rstu8901...",
  "data": {
    "id": "txn_550e8400-e29b-41d4-a716-446655440005",
    "user_id": "user_123",
    "transaction_type": "PAYOUT",
    "amount": "10000.00",
    "asset_code": "ZAR",
    "status": "FAILED",
    "reference_id": "FW-20250511-001234",
    "transaction_id": "PAYOUT12345",
    "recipient_currency": "ZAR",
    "bank_name": "ABSA Bank",
    "bank_account": "9876543210",
    "withdrawal_recipient_name": "John Doe",
    "receiver_user": {
      "first_name": "John",
      "last_name": "Doe",
      "businessName": null,
      "role": null
    },
    "receiver_wallet_details": {
      "address": null,
      "network": null,
      "currency": "ZAR",
      "country": null,
      "bank_code": "123456",
      "bank_name": "ABSA Bank",
      "account_number": "9876543210"
    },
    "created_at": "2025-05-11T10:40:00Z",
    "updated_at": "2025-05-12T10:10:00Z"
  }
}

Important Fields:

`status`: Always FAILED for this event
`reference_id`: Use for tracking
`bank_account`: Intended receiving bank account

payout.cancelled

Description: Triggered when a payout is cancelled. Triggered When:

User cancels the payout before processing
Admin cancels the transaction
Cancels due to compliance/fraud checks
Transaction status changes to CANCELLED

Payload Example:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440009",
  "timestamp": 1715420800000,
  "event_type": "payout.cancelled",
  "signature": "t=1715420800000,s=ghij7890klmn1234opqr5678stuv9012...",
  "data": {
    "id": "txn_550e8400-e29b-41d4-a716-446655440005",
    "user_id": "user_123",
    "transaction_type": "PAYOUT",
    "amount": "10000.00",
    "asset_code": "ZAR",
    "status": "CANCELLED",
    "reference_id": "FW-20250511-001234",
    "transaction_id": "PAYOUT12345",
    "recipient_currency": "ZAR",
    "bank_name": "ABSA Bank",
    "bank_account": "9876543210",
    "withdrawal_recipient_name": "John Doe",
    "receiver_user": {
      "first_name": "John",
      "last_name": "Doe",
      "businessName": null,
      "role": null
    },
    "receiver_wallet_details": {
      "address": null,
      "network": null,
      "currency": "ZAR",
      "country": null,
      "bank_code": "123456",
      "bank_name": "ABSA Bank",
      "account_number": "9876543210"
    },
    "created_at": "2025-05-11T10:40:00Z",
    "updated_at": "2025-05-11T10:50:00Z"
  }
}

Important Fields:

`status`: Always CANCELLED for this event
`reference_id`: Use for tracking

Webhook Payload Structure

All webhook payloads follow this structure:

{
  "id": "evt_<unique-id>",
  "timestamp": 1715420400000,
  "event_type": "<event-type>",
  "signature": "t=<timestamp>,s=<sig>",
  "data": {
    // Event-specific transaction data goes here
  }
}

Fields:

`id`: Unique event ID
`timestamp`: Unix timestamp in milliseconds
`event_type`: Event type string
`data`: Event-specific transaction data

Signature Verification

All webhooks are signed with HMAC-SHA256. To verify:

Extract `t` (timestamp) and `s` (signature) from the signature header
Create message: timestamp + ”.” + stringified_payload
Generate HMAC-SHA256 with your signing secret
Compare computed signature with received signature

Security Tips:

Always verify the signature before processing
Check timestamp is recent (within 5 minutes recommended)
Store `signing_secret` securely, never expose in client-side code
Implement idempotency using event `id` to handle retries

Common Transaction Data Fields

All transaction payloads include these core fields:

Field	Type	Description
`id`	string	Unique transaction identifier
`user_id`	string	User who initiated the transaction
`transaction_type`	string	DEPOSIT, WITHDRAWAL, PAYOUT
`amount`	string	Transaction amount (decimal)
`currency`	string	Base currency (USDC, ZAR, NGN, etc.)
`status`	string	Current transaction status
`description`	string	Human-readable description
`created_at`	ISO 8601	Timestamp when created
`updated_at`	ISO 8601	Timestamp of last update

Retry Policy

StableStack retries failed webhook deliveries with exponential backoff:

Attempt	Wait Time
1st	Immediate
2nd	1 minute
3rd	5 minutes
4th	30 minutes
5th	4 hours

Retry Conditions:

✅ Retried: 5xx errors, timeouts, network errors, 408, 429
❌ Not retried: 4xx errors (except 408, 429)

Best Practices:

Respond with 2xx status immediately
Process webhook asynchronously
Use event `id` for idempotency
Implement your own retry logic for downstream failures

Testing Webhooks

Use the dashboard to:

Send test events
View delivery history
Check response logs
Verify signature validation

See Webhook Security for testing signature verification.

Get Started

Webhooks

Libraries

Coverage

Use Cases

Prohibited

Overview

Event Types

Wallet Events

wallet.transaction.inbound

wallet.transaction.outbound

Payout Events

payout.initiated

payout.processing

payout.completed

payout.failed

payout.cancelled

Webhook Payload Structure

Signature Verification

Common Transaction Data Fields

Retry Policy

Testing Webhooks

​Overview

​Event Types

​Wallet Events

​wallet.transaction.inbound

​wallet.transaction.outbound

​Payout Events

​payout.initiated

​payout.processing

​payout.completed

​payout.failed

​payout.cancelled

​Webhook Payload Structure

​Signature Verification

​Common Transaction Data Fields

​Retry Policy

​Testing Webhooks

Overview

Event Types

Wallet Events

wallet.transaction.inbound

wallet.transaction.outbound

Payout Events

payout.initiated

payout.processing

payout.completed

payout.failed

payout.cancelled

Webhook Payload Structure

Signature Verification

Common Transaction Data Fields

Retry Policy

Testing Webhooks