POST /your/webhook/endpoint HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-HMAC-Signature: <hmac_sha256_signature>
X-Event-ID: <event_correlation_id>
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "550e8400-e29b-41d4-a716-446655440001",
  "externalReferenceId": "550e8400-e29b-41d4-a716-446655440002",
  "eventType": "WIDGET_DEPOSIT_COMPLETE",
  "amount": 50.00
}

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "550e8400-e29b-41d4-a716-446655440001",
  "externalReferenceId": "550e8400-e29b-41d4-a716-446655440002",
  "eventType": "WIDGET_KYC_INITIATION",
  "appId": "550e8400-e29b-41d4-a716-446655440003"
}

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "550e8400-e29b-41d4-a716-446655440001",
  "externalReferenceId": "550e8400-e29b-41d4-a716-446655440002",
  "appId": "550e8400-e29b-41d4-a716-446655440003",
  "eventType": "WIDGET_DEPOSIT_COMPLETE",
  "amount": 50.00
}

{
  "recordId": "cec87136-38d5-4001-8eb9-310f330520a2",
  "user": "Amir Test",
  "accountId": "ff30139d-54ae-4483-8683-a07f6edbf13b",
  "amount": -58,
  "initialAmount": 58,
  "bonusCashbackRate": 0,
  "cardDisplayName": "",
  "cardLastFour": "0184",
  "cashBalanceAvailableBalance": 0,
  "cashBalanceDepositIds": null,
  "cashBalanceTotalBalance": 0,
  "cashback": 0.87,
  "cashbackRate": 1.5,
  "category": "Miscellaneous Specialty Retail",
  "challengeLogoUrl": null,
  "channel": null,
  "conversionRate": 1,
  "createdAt": "2026-05-06T16:55:16.176Z",
  "depositIds": null,
  "description": "Uber",
  "descriptorId": "2f30bea0-33a9-4b4b-95ce-b19662821d45",
  "destination": "Uber",
  "eventType": "TRANSACTION_CREATE",
  "externalFundingSourceActivity": -58,
  "fee": 0,
  "fluzBalanceActivity": 0.87,
  "giftCardPrepaymentBalanceAvailableBalance": 1002537.605,
  "giftCardPrepaymentBalanceTotalBalance": 1002537.605,
  "invitedAccountId": null,
  "isCashBalanceAffected": false,
  "isGiftCardBalanceAffected": false,
  "isReserveBalanceAffected": false,
  "isSeatBalanceAffected": true,
  "liabilityId": null,
  "logoUrl": "https://storage.googleapis.com/fluz-fluz-file-uploads-prod-ricuyxowbwlfprel/UBER-logo.jpg",
  "merchantId": "9f83fa82-435e-4553-9525-8c7871825f74",
  "merchantCategoryCode": 5999,
  "merchantCategoryDescription": "Miscellaneous Specialty Retail",
  "merchantCity": "No_city",
  "merchantCountry": "USA",
  "merchantIndustry": "Travel",
  "merchantName": "Uber",
  "note": null,
  "originalCurrencyAmount": 5800,
  "originalCurrencyCode": "USD",
  "otherCashBalanceAvailableBalance": 419594.8,
  "otherCashBalanceTotalBalance": 419594.8,
  "platformInstitutionLogo": null,
  "referenceId": "1047143",
  "reserveBalanceAvailableBalance": 0,
  "reserveBalanceTotalBalance": 0,
  "seatBalanceAvailableBalance": 1708.644,
  "seatBalanceTotalBalance": 1708.644,
  "source": "ACH Plaid Silver Standard 0.1% Interest Saving 1111 [$58.00]",
  "sourceType": null,
  "status": "PENDING",
  "transactionId": "cec87136-38d5-4001-8eb9-310f330520a2",
  "transactionType": "Virtual Card Purchase",
  "transferId": null,
  "usedUserCashBalanceId": null,
  "userId": "c6606c0e-f22f-4eee-85e5-17be6ae407bc",
  "virtualCardId": "7761e937-b9d7-4c71-b74e-2d9bbc9249ac",
  "virtualCardProgram": "HIGHNOTE_CFSB_MASTERCARD",
  "withdrawIds": null
}

{
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionType": "PURCHASE",
  "amount": 25.99,
  "fluzAmount": 0,
  "externalFundingAmount": 25.99,
  "currency": "USD",
  "sourceRecordType": "VirtualCardTransaction",
  "sourceRecordId": "d4e5f6a7-b890-1234-cdef-567890abcdef",
  "accountId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "userId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "source": "CARD",
  "destination": "Merchant Name",
  "status": "DECLINED",
  "merchantId": "e5f6a7b8-9012-3456-def0-1234567890ab",
  "descriptorId": "f6a7b890-1234-5678-ef01-234567890abc",
  "liabilityId": "a7b89012-3456-7890-f012-34567890abcd",
  "vendorName": "Highnote",
  "merchantName": "Amazon.com",
  "merchantCountry": "US",
  "merchantCity": "Seattle",
  "merchantState": "WA",
  "logoUrl": "https://cdn.fluz.app/merchants/amazon-logo.png",
  "category": "Shopping",
  "cardLastFour": "4321",
  "cardDisplayName": "My Virtual Card",
  "virtualCardId": "b8901234-5678-90ab-0123-4567890abcde",
  "virtualCardProgram": "HIGHNOTE",
  "channel": "MOBILE_APP",
  "externalFundingSourceType": "BANK_CARD",
  "externalFundingSourceId": "c9012345-6789-0abc-1234-567890abcdef",
  "fundingSourceSubtype": "DEBIT",
  "isCashBalanceUsed": false,
  "isPrepaymentBalanceUsed": false,
  "isRewardsBalanceUsed": false,
  "isReserveBalanceUsed": false,
  "transactionDateTime": "2025-03-19T12:00:00.000Z",
  "spendAccountNickname": "Daily Spending",
  "declineTitle": "Transaction Declined",
  "declineReason": "Insufficient spend limit",
  "declineDescription": "Your virtual card spend limit has been exceeded for this period.",
  "declineCtaText": "Review Spend Limits",
  "declineCategory": "SPEND_LIMIT",
  "offerId": "d0123456-7890-abcd-2345-67890abcdef0",
  "issuer": "Highnote",
  "bin": "423456",
  "limitAmount": "500.00",
  "limitDuration": "MONTHLY",
  "lockOnNextUse": "false",
  "lockDate": null,
  "bankAccountNickname": "Chase Checking",
  "bankAccountLastFour": "7890",
  "isPrivate": true
}

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, apiKey) {
  const computedSignature = crypto
    .createHmac('sha256', apiKey)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

// Express.js example
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-hmac-signature'];
  const eventId = req.headers['x-event-id'];
  
  if (!verifyWebhookSignature(req.body, signature, YOUR_API_KEY)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  const { eventType, userId, amount } = req.body;
  
  console.log(`Received ${eventType} for user $USERID`);
  
  // Always respond with 200 to acknowledge receipt
  res.status(200).send('OK');
});

import hmac
import hashlib
import json

def verify_webhook_signature(payload: dict, signature: str, api_key: str) -> bool:
    payload_string = json.dumps(payload, separators=(',', ':'))
    computed_signature = hmac.new(
        api_key.encode('utf-8'),
        payload_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, computed_signature)

# Flask example
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-HMAC-Signature')
    event_id = request.headers.get('X-Event-ID')
    payload = request.json
    
    if not verify_webhook_signature(payload, signature, YOUR_API_KEY):
        return 'Invalid signature', 401
    
    # Process the webhook
    event_type = payload['eventType']
    user_id = payload['userId']
    
    print(f"Received {event_type} for user USER_ID")
    
    # Always respond with 200
    return 'OK', 200

app.post('/webhook', express.json(), async (req, res) => {
  const signature = req.headers['x-hmac-signature'];
  
  // 1. Verify signature
  if (!verifyWebhookSignature(req.body, signature, YOUR_API_KEY)) {
    return res.status(401).send('Invalid signature');
  }
  
  // 2. Respond immediately
  res.status(200).send('OK');
  
  // 3. Process asynchronously
  processWebhookAsync(req.body).catch(err => {
    console.error('Error processing webhook:', err);
  });
});

async function processWebhookAsync(payload) {
  const { eventType, userId, accountId, amount } = payload;
  
  switch (eventType) {
    case 'WIDGET_DEPOSIT_COMPLETE':
      await updateUserBalance(userId, amount);
      break;
    case 'WIDGET_WITHDRAW_COMPLETE':
      await recordWithdrawal(userId, amount);
      break;
    // ... handle other events
  }
}

const processedEvents = new Set(); // Use Redis/DB in production

app.post('/webhook', async (req, res) => {
  const eventId = req.headers['x-event-id'];
  
  // Check if already processed
  if (processedEvents.has(eventId)) {
    console.log(`Event ${eventId} already processed, skipping`);
    return res.status(200).send('OK');
  }
  
  // Verify signature
  if (!verifyWebhookSignature(req.body, req.headers['x-hmac-signature'], API_KEY)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Respond immediately
  res.status(200).send('OK');
  
  // Mark as processed
  processedEvents.add(eventId);
  
  // Process event
  await processWebhookAsync(req.body);
});