Webhooks

Stay informed about transaction status changes in real-time with our webhook system. Webhooks enable your application to receive instant notifications when transactions are processed, updated, or completed on our platform.

Overview

Webhooks are HTTP POST requests automatically sent to your specified endpoint URL when transaction events occur. This eliminates the need for constant polling and ensures your application stays synchronized with the latest transaction statuses.

Key Benefits:

• Real-time transaction updates
• Reduced API calls and improved efficiency
• Immediate notification of status changes
• Reliable event delivery with retry logic

Supported Events

We send webhooks for the following transaction events:

OnchainTransaction Events

Triggered when blockchain transactions change status:

• Deposits - Incoming asset deposits to user wallets
• Withdrawals - Outgoing asset withdrawals from user wallets
• Status Updates - Transaction confirmations, failures, or other state changes

InternalTransaction Events

Triggered when internal platform transfers occur:

• Wallet-to-Wallet Off- chain Transfers - Instant transfers off-chain on Knova ledger free of network fees
• Status Changes - Transfer completions, failures, or processing updates

Webhook Payload

Every webhook request contains a WebhookNotification object with the following structure:

{
  "id": "webhook_abc123",
  "event_type": "OnchainTransaction",
  "payload": {
    "OnchainTransaction": {
      "id": "txn_def456",
      "user_id": "user_789",
      "asset_code": "USDC_ETH",
      "tx_hash": "0x1234567890abcdef...",
      "amount": "0.001",
      "status": "Confirmed",
      "created": "2023-06-15T10:30:00Z",
      "updated": "2023-06-15T10:35:00Z"
    }
  },
  "created": "2023-06-15T10:35:00Z"
}

Implementation Guide

1. Configure Webhook Endpoint

Set up an HTTPS endpoint that can receive POST requests. Your endpoint should:

• Accept JSON payloads
• Respond with HTTP 200-299 status codes
• Process requests within 30 seconds

2. Handle Webhook Events

Parse the incoming webhook and process based on event_type:

app.post('/webhooks', (req, res) => {
  const webhook = req.body;
  
  switch (webhook.event_type) {
    case 'OnchainTransaction':
      handleOnchainTransaction(webhook.payload.OnchainTransaction);
      break;
    case 'InternalTransaction':
      handleInternalTransaction(webhook.payload.InternalTransaction);
      break;
  }
  
  res.status(200).send('OK');
});

3. Process Transaction Updates

Update your application state based on the transaction status:

function handleOnchainTransaction(transaction) {
  const { id, user_id, status, amount, asset_code } = transaction;
  
  if (status === 'Confirmed') {
    // Credit user account, send confirmation email
    creditUserAccount(user_id, amount, asset_code);
    sendConfirmationEmail(user_id, transaction);
  } else if (status === 'Failed') {
    // Handle failed transaction, notify user
    handleFailedTransaction(user_id, transaction);
  }
}

Security & Best Practices

Common Use Cases

Testing Webhooks

Use our sandbox environment to test webhook integration:

1. Configure Test Endpoint - Set up a webhook URL in sandbox mode
2. Generate Test Transactions - Create test deposits/withdrawals to trigger webhooks
3. Verify Payload Processing - Ensure your application handles all event types correctly
4. Test Error Scenarios - Simulate failures to verify error handling

Next Steps

Ready to implement webhooks?

1. Set up your webhook endpoint URL
2. Configure webhook settings in your dashboard
3. Test with sandbox transactions
4. Go live and monitor webhook delivery

For technical support or questions about webhook implementation, contact our developer support team.