Webhooks

Everything you need to know for using WalletCloud's webhooks in your applications. Get notifications for external transfers, internal transfers, and token transfers.

Webhooks are a way for you to subscribe to events that occur on your wallets. This guide will walk through what webhooks are and how you can use them in order to get started with integrating them into your application.

What are Webhooks?

Webhooks are a way for users to receive notifications when an event occurs on your wallet. Rather than continuously polling the server to check if the state has changed, webhooks provide information to you as it becomes available, which is a lot more efficient and beneficial for developers. Webhooks work by registering a URL to send notifications to once certain events occur.

One may think of webhook notifications as SMS notifications. The entity sending the message has your registered phone number and they send a specific message payload to that phone number. You then have the ability to respond confirming you have received it, creating a two-way communication stream.

Types of Webhooks

Wallet Transaction Webhooks

WalletCloud currently offers the Wallet Transaction webhooks (WALLET_TRANSACTION). This webhooks are sent to your url when there is a transaction on your wallet. Furthermore, the transaction property in the webhook payload that will be sent to your url will also contain a type. The supported transaction types include:

1. RECEIVED_ASSET: This webhook is sent when an address on your wallet receives a transaction such as a token transfer.

2. SENT_ASSET: This webhook is sent when your wallet sends out tokens to external addresses. This webhooks notifies you of the status of the transaction.

Example payload

{
  "walletId": "86f6061c-0b6e-4e20-aa57-bc25152c460d",
  "network": "TESTNET",
  "webhookType": "WALLET_TRANSACTION",
  "timestamp": "Monday, October 4, 2021 11:44 PM",
  "transaction": {
    "id": "ef200e5f-13f2-4d0f-9fec-b909eda09771",
    "type": "RECEIVED_ASSET",
    "fromAddress": "0xc83cCcd964FAe2174749A3B5CAe65d6C60c28Db2",
    "toAddress": "0x2ef0c488d2b1a7f9dab5b6c88c91482a6195616e",
    "blockNumber": 9408647,
    "hash": "0xf9acf43d734d7d209b1407f3d4fc1f14faaf75fccfc2aa9578170a814ef8d0ee",
    "value": 7.34,
    "asset": "USDC",
    "confirmed": true,
    "confirmations": 29709
  }
}

How To Set Up Webhooks

Navigate to your wallet dashboard on WalletCloud.

1. Click on the settings tab.

2. Scroll to the webhooks section and add your webhook url.

3. Click on the "Test Webhook" button to verify that you webhook works correctly. (We will send a demo payload to your webhook url which you can inspect).

4. Click on save changes to save your webhook.

Webhook Signature and Security

To verify the authenticity of WalletCloud's webhooks, you can verify that they originated from WalletCloud by generating a HMAC SHA-256 hash code using your Wallet API key and request body. Take the following steps to verify a webhook signature:

1. Find your wallet API key on your wallet dashboard

2. Validate the payload signature

Every webhook payload will contain a hashed authentication signature in the header which is computed by generating a hash from concatenating your wallet API key and request body, using the HMAC SHA256 hash algorithm.

In order to verify this signature came from WalletCloud, you simply have to generate the HMAC SHA256 hash and compare it with the signature received.

Example Request Header

POST /yourWebhookServer/push HTTP/1.1
Content-Type: application/json;
X-WalletCloud-Signature: your-hashed-signature

Example Signature Validation Function

function isValidSignature(request) {    
    const apiKey = 'Wallet API key from your Wallet dashboard';
    const headers = request.headers;
    const signature = headers['x-walletcloud-signature']; // Lowercase for NodeJS
    const body = request.body;    
    const hmac = crypto.createHmac('sha256', apiKey) // Create a HMAC SHA256 hash using your wallet API key
    hmac.update(JSON.stringify(body), 'utf8') // Update the token hash with the request body using utf8
    const digest = hmac.digest('hex');     
    return (signature === digest); // If signature equals your computed hash, return true
}