Implementation Guide

// Express.js example
const express = require('express');
const crypto = require('crypto');

const app = express();

// IMPORTANT: Use raw body for signature verification
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/aiprise/business/events', async (req, res) => {
  try {
    // Step 1: Verify signature
    const signature = req.headers['x-hmac-signature'];
    const rawBody = req.body.toString('utf8');
    const expectedSignature = crypto
      .createHmac('sha256', process.env.AIPRISE_API_KEY)
      .update(rawBody)
      .digest('hex');
    
    if (signature !== expectedSignature) {
      console.error('Invalid signature');
      return res.status(401).send('Unauthorized');
    }
    
    // Step 2: Parse the payload
    const payload = JSON.parse(rawBody);
    
    // Step 3: Identify event type
    const eventType = payload.event_type || payload.business_profile_event_type;
    
    // Step 4: Process based on event type
    await processBusinessEvent(payload, eventType);
    
    // Step 5: Respond quickly (200 OK)
    res.status(200).send('OK');
    
  } catch (error) {
    console.error('Business webhook processing error:', error);
    res.status(500).send('Internal Server Error');
  }
});

async function processBusinessEvent(payload, eventType) {
  switch(eventType) {
    case 'VERIFICATION_SESSION_STARTED':
      await handleBusinessSessionStarted(payload);
      break;
      
    case 'VERIFICATION_SESSION_COMPLETION':
      await handleBusinessSessionCompletion(payload);
      break;
      
    case 'RUN_BUSINESS_VERIFICATION':
      await handleBusinessProfileVerification(payload);
      break;
      
    case 'BUSINESS_OFFICER_RUN_KYC':
      await handleOfficerKYC(payload);
      break;
      
    case 'ADD_BUSINESS_OFFICER':
      await handleOfficerAdded(payload);
      break;
      
    case 'AML_MONITORING_UPDATE_BUSINESS_VERIFICATION':
    case 'AML_MONITORING_UPDATE_RELATED_BUSINESS_OFFICER':
      await handleBusinessAMLUpdate(payload);
      break;
      
    default:
      console.log(`Unhandled business event type: ${eventType}`);
  }
}

async function handleBusinessSessionStarted(payload) {
  await db.businessVerificationSessions.update(
    { id: payload.verification_session_id },
    { 
      status: 'IN_PROGRESS',
      started_at: new Date()
    }
  );
  
  // Notify compliance team
  await notifyComplianceTeam(
    payload.client_reference_id,
    'New business verification started'
  );
}

async function handleBusinessProfileVerification(payload) {
  const decision = payload.aiprise_summary.decision;
  const businessProfileId = payload.business_profile_id;
  
  // Update business profile
  await db.businessProfiles.update(
    { id: businessProfileId },
    {
      verification_status: decision,
      verified_at: decision === 'APPROVED' ? new Date() : null,
      kyb_completed: true
    }
  );
  
  // Process officers
  if (payload.related_persons) {
    for (const officer of payload.related_persons) {
      await db.businessOfficers.upsert({
        business_profile_id: businessProfileId,
        person_reference_id: officer.person_reference_id,
        roles: officer.roles,
        ownership_percent: officer.ownership_percent,
        verification_status: officer.verification_status
      });
    }
  }
  
  // Process related companies
  if (payload.related_companies) {
    for (const company of payload.related_companies) {
      await db.relatedCompanies.upsert({
        business_profile_id: businessProfileId,
        company_reference_id: company.company_reference_id,
        legal_name: company.legal_name,
        relationship_type: company.relationship_type,
        ownership_percent: company.ownership_percent
      });
    }
  }
  
  // Business logic based on decision
  if (decision === 'APPROVED') {
    await enableBusinessAccount(businessProfileId);
    await setTransactionLimits(businessProfileId, payload.risk_info);
    await generateServiceAgreement(businessProfileId);
  } else if (decision === 'DECLINED') {
    await notifyBusinessDecline(businessProfileId, payload.aiprise_summary.reasons);
  }
}

async function handleOfficerKYC(payload) {
  const businessProfileId = payload.business_profile_id;
  const personReferenceId = payload.person_reference_id;
  const decision = payload.aiprise_summary.decision;
  
  // Update officer record
  await db.businessOfficers.update(
    {
      business_profile_id: businessProfileId,
      person_reference_id: personReferenceId
    },
    {
      kyc_status: decision,
      kyc_completed_at: new Date(),
      aml_status: payload.aml_info?.result
    }
  );
  
  // Check if all officers are verified
  const allOfficers = await db.businessOfficers.findAll({
    where: { business_profile_id: businessProfileId }
  });
  
  const allVerified = allOfficers.every(
    officer => officer.kyc_status === 'APPROVED'
  );
  
  if (allVerified) {
    await db.businessProfiles.update(
      { id: businessProfileId },
      { all_officers_verified: true }
    );
    
    // Trigger next step in onboarding
    await triggerBusinessOnboardingStep(businessProfileId, 'OFFICERS_VERIFIED');
  }
}

app.listen(3000);

// Separate endpoint for business decision callbacks
app.post('/webhooks/aiprise/business/decision', async (req, res) => {
  try {
    // Verify signature (same as above)
    const signature = req.headers['x-hmac-signature'];
    const rawBody = req.body.toString('utf8');
    const expectedSignature = crypto
      .createHmac('sha256', process.env.AIPRISE_API_KEY)
      .update(rawBody)
      .digest('hex');
    
    if (signature !== expectedSignature) {
      return res.status(401).send('Unauthorized');
    }
    
    const payload = JSON.parse(rawBody);
    
    // Process final KYB decision
    await processBusinessDecision(payload);
    
    res.status(200).send('OK');
    
  } catch (error) {
    console.error('Business decision callback error:', error);
    res.status(500).send('Internal Server Error');
  }
});

async function processBusinessDecision(payload) {
  const decision = payload.aiprise_summary.decision;
  const businessId = payload.client_reference_id;
  
  // Make idempotent using verification_session_id
  const existing = await db.businessVerificationResults.findOne({
    verification_session_id: payload.verification_session_id
  });
  
  if (existing) {
    console.log('Business decision already processed');
    return;
  }
  
  // Store KYB result
  await db.businessVerificationResults.create({
    verification_session_id: payload.verification_session_id,
    business_id: businessId,
    decision: decision,
    payload: payload,
    processed_at: new Date()
  });
  
  // Update business record
  await db.businesses.update(
    { id: businessId },
    {
      kyb_status: decision,
      kyb_completed_at: new Date(),
      registry_verified: payload.registration_info?.good_standing,
      aml_clear: payload.aml_info?.result === 'CLEAR',
      risk_tier: payload.risk_info?.risk_tier,
      credit_score: payload.lookup_info?.find(l => l.provider === 'credit_bureau')?.credit_score
    }
  );
  
  // Store officers
  if (payload.related_persons) {
    for (const officer of payload.related_persons) {
      await db.businessOfficers.create({
        business_id: businessId,
        person_reference_id: officer.person_reference_id,
        first_name: officer.user_profile.first_name,
        last_name: officer.user_profile.last_name,
        roles: officer.roles,
        ownership_percent: officer.ownership_percent,
        kyc_status: officer.verification_status
      });
    }
  }
  
  // Business decision logic
  switch(decision) {
    case 'APPROVED':
      await approveBusinessOnboarding(businessId, payload);
      break;
      
    case 'DECLINED':
      await declineBusinessOnboarding(businessId, payload.aiprise_summary.reasons);
      break;
      
    case 'MANUAL_REVIEW':
      await queueForComplianceReview(businessId, payload);
      break;
  }
}

async function approveBusinessOnboarding(businessId, payload) {
  // Enable business account
  await db.businesses.update(
    { id: businessId },
    { 
      account_status: 'ACTIVE',
      activated_at: new Date()
    }
  );
  
  // Set transaction limits based on risk
  const riskTier = payload.risk_info?.risk_tier;
  const limits = calculateTransactionLimits(riskTier);
  
  await db.businessLimits.create({
    business_id: businessId,
    daily_limit: limits.daily,
    monthly_limit: limits.monthly,
    transaction_limit: limits.transaction
  });
  
  // Generate contract
  await generateBusinessContract(businessId);
  
  // Notify business
  await sendBusinessApprovalEmail(businessId);
  
  // Notify account manager
  const accountManager = payload.client_reference_data?.account_manager;
  if (accountManager) {
    await notifyAccountManager(accountManager, businessId, 'approved');
  }
}

async function handleOfficerAdded(payload) {
  const businessProfileId = payload.business_profile_id;
  const officer = payload.user_profile;
  const personReferenceId = payload.person_reference_id;
  
  // Create officer record
  await db.businessOfficers.create({
    business_profile_id: businessProfileId,
    person_reference_id: personReferenceId,
    first_name: officer.first_name,
    last_name: officer.last_name,
    email: officer.email,
    phone: officer.phone,
    roles: payload.roles,
    ownership_percent: payload.ownership_percent,
    shares_allocated: payload.shares_allocated,
    kyc_status: 'PENDING',
    created_at: new Date()
  });
  
  // Check if KYC is required for this officer
  const requiresKYC = payload.roles.some(role => 
    ['CEO', 'CFO', 'DIRECTOR', 'UBO'].includes(role)
  ) || payload.ownership_percent >= 25;
  
  if (requiresKYC) {
    // Generate KYC link for officer
    const kycUrl = await aipriseAPI.createOfficerKYCSession({
      business_profile_id: businessProfileId,
      person_reference_id: personReferenceId
    });
    
    // Send KYC invitation
    await sendOfficerKYCInvitation(officer.email, kycUrl);
  }
}

async function handleOfficerKYCCompletion(payload) {
  const businessProfileId = payload.business_profile_id;
  const personReferenceId = payload.person_reference_id;
  const kycDecision = payload.aiprise_summary.decision;
  
  // Update officer KYC status
  await db.businessOfficers.update(
    {
      business_profile_id: businessProfileId,
      person_reference_id: personReferenceId
    },
    {
      kyc_status: kycDecision,
      kyc_completed_at: new Date(),
      id_verified: payload.id_info?.authenticity?.result === 'PASS',
      face_matched: payload.face_match_info?.result === 'PASS',
      aml_status: payload.aml_info?.result
    }
  );
  
  // If officer is declined, flag for review
  if (kycDecision === 'DECLINED') {
    await createComplianceTicket({
      business_profile_id: businessProfileId,
      issue_type: 'OFFICER_KYC_DECLINED',
      person_reference_id: personReferenceId,
      details: payload.aiprise_summary.reasons
    });
  }
  
  // Check overall business verification progress
  await checkBusinessVerificationProgress(businessProfileId);
}