Automated B2B Vendor Onboarding: MSA & W-9 Signing via API (2026)

import crypto from "crypto";
import express, { Request, Response } from "express";

const SIGNBEE_API_URL = "https://api.signb.ee/v1/documents";
const SIGNBEE_API_KEY = process.env.SIGNBEE_API_KEY!;
const WEBHOOK_SIGNING_SECRET = process.env.SIGNBEE_WEBHOOK_SECRET!;

interface VendorIntakePayload {
  vendorId: string;
  companyName: string;
  signatoryName: string;
  signatoryEmail: string;
  ein: string;
  requiresDataSecurityAddendum: boolean;
}

interface DocumentDispatchResult {
  documentId: string;
  docType: "MSA" | "ISA" | "W9";
  signingUrl: string;
}

/**
 * 1. Dispatch Multi-Document Onboarding Packet via Signbee REST API
 */
export async function dispatchVendorOnboardingPacket(
  vendor: VendorIntakePayload
): Promise<DocumentDispatchResult[]> {
  const documentsToDispatch: Array<{
    docType: "MSA" | "ISA" | "W9";
    title: string;
    markdown: string;
  }> = [];

  // 1. Master Services Agreement (MSA) Markdown
  const msaMarkdown = `# MASTER SERVICES AGREEMENT
**Effective Date:** ${new Date().toISOString().split("T")[0]}
**Company:** Acquired Global Platforms Inc. ("Client")
**Vendor:** ${vendor.companyName} ("Vendor")

## 1. Services and Scope
Vendor agrees to provide commercial deliverables as defined in executed Statements of Work (SOW).

## 2. Payment and Net Terms
Client will issue payments within forty-five (45) days of receipt of an undisputed electronic invoice.

## 3. Representations & Warranties
Vendor certifies compliance with all applicable federal, state, and international employment and tax statutes.

## 4. Limitation of Liability
Neither party shall be liable for indirect, incidental, or consequential damages arising from this Agreement.
`;

  documentsToDispatch.push({
    docType: "MSA",
    title: `MSA - ${vendor.companyName}`,
    markdown: msaMarkdown,
  });

  // 2. Information Security Addendum (ISA) if vendor accesses customer data
  if (vendor.requiresDataSecurityAddendum) {
    const isaMarkdown = `# INFORMATION SECURITY & DATA PROCESSING ADDENDUM
**Vendor Entity:** ${vendor.companyName}
**Vendor ID:** ${vendor.vendorId}

## 1. Security Safeguards
Vendor shall maintain technical and organizational safeguards conforming to SOC 2 Type II and ISO/IEC 27001:2022 standards.

## 2. Encryption Standard
All customer data in transit must be encrypted using TLS 1.3, and data at rest must use AES-256 GCM.

## 3. Security Breach Notification
Vendor shall notify Client within twenty-four (24) hours of discovering any confirmed or suspected unauthorized access to Client systems.
`;
    documentsToDispatch.push({
      docType: "ISA",
      title: `Security Addendum - ${vendor.companyName}`,
      markdown: isaMarkdown,
    });
  }

  // 3. IRS Form W-9 Substitute Certification Markdown
  const w9Markdown = `# FORM W-9 SUBSTITUTE TAXPAYER IDENTIFICATION CERTIFICATION
**Taxpayer Legal Name:** ${vendor.companyName}
**Employer Identification Number (EIN):** ${vendor.ein}
**Signatory:** ${vendor.signatoryName}

Under penalties of perjury, I certify that:
1. The number shown on this form is my correct taxpayer identification number (or I am waiting for a number to be issued to me); and
2. I am not subject to backup withholding because: (a) I am exempt from backup withholding, or (b) I have not been notified by the IRS that I am subject to backup withholding; and
3. I am a U.S. citizen or other U.S. person (as defined in IRS instructions).

*The Internal Revenue Service does not require your consent to any provision of this document other than the certifications required to avoid backup withholding.*
`;
  documentsToDispatch.push({
    docType: "W9",
    title: `W-9 Tax Certification - ${vendor.companyName}`,
    markdown: w9Markdown,
  });

  // Execute dispatches sequentially or concurrently
  const results: DocumentDispatchResult[] = [];

  for (const doc of documentsToDispatch) {
    const response = await fetch(SIGNBEE_API_URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${SIGNBEE_API_KEY}`,
      },
      body: JSON.stringify({
        title: doc.title,
        content: doc.markdown,
        sender_name: "Procurement Legal Team",
        sender_email: "procurement@acquired.com",
        recipient_name: vendor.signatoryName,
        recipient_email: vendor.signatoryEmail,
        metadata: {
          vendor_id: vendor.vendorId,
          document_type: doc.docType,
        },
      }),
    });

    if (!response.ok) {
      const errText = await response.text();
      throw new Error(`Failed to dispatch ${doc.docType} for ${vendor.vendorId}: ${errText}`);
    }

    const data = await response.json();
    results.push({
      documentId: data.id,
      docType: doc.docType,
      signingUrl: data.signing_url,
    });

    // Record document dispatch in local database state machine
    await saveVendorDocumentRecord(vendor.vendorId, data.id, doc.docType, "DISPATCHED");
  }

  return results;
}

/**
 * 2. Express Webhook Listener with Timing-Safe HMAC-SHA256 Verification
 */
export function createVendorWebhookRouter() {
  const router = express.Router();

  router.post(
    "/api/webhooks/signbee",
    express.raw({ type: "application/json" }),
    async (req: Request, res: Response) => {
      const signatureHeader = req.headers["x-signbee-signature"] as string;
      if (!signatureHeader) {
        return res.status(401).json({ error: "Missing signature header" });
      }

      // Timing-safe HMAC verification
      const rawBody = req.body.toString();
      const expectedHmac = crypto
        .createHmac("sha256", WEBHOOK_SIGNING_SECRET)
        .update(rawBody)
        .digest("hex");

      const isValid =
        signatureHeader.length === expectedHmac.length &&
        crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expectedHmac));

      if (!isValid) {
        return res.status(401).json({ error: "Invalid cryptographic signature" });
      }

      const payload = JSON.parse(rawBody);
      const { event, data } = payload;

      // Handle document.completed event
      if (event === "document.completed") {
        const { id: documentId, metadata, pdf_url, certificate_hash } = data;
        const vendorId = metadata?.vendor_id;
        const docType = metadata?.document_type;

        if (vendorId && docType) {
          await updateDocumentStatus(vendorId, documentId, "COMPLETED", pdf_url, certificate_hash);

          // Collate state: check if all required vendor documents are now signed
          const isFullyOnboarded = await checkVendorPacketCompletion(vendorId);

          if (isFullyOnboarded) {
            await triggerErpVendorActivation(vendorId);
          }
        }
      }

      return res.status(200).json({ received: true });
    }
  );

  return router;
}

// Database helper mocks
async function saveVendorDocumentRecord(vendorId: string, docId: string, type: string, status: string) {
  console.log(`[DB] Vendor ${vendorId} - ${type} (${docId}) status: ${status}`);
}
async function updateDocumentStatus(vendorId: string, docId: string, status: string, pdfUrl: string, hash: string) {
  console.log(`[DB] Vendor ${vendorId} doc ${docId} completed with hash ${hash}`);
}
async function checkVendorPacketCompletion(vendorId: string): Promise<boolean> {
  // Queries DB to verify MSA, ISA (if required), and W9 are all COMPLETED
  return true; 
}
async function triggerErpVendorActivation(vendorId: string) {
  console.log(`[ERP ACTIVATION] Vendor ${vendorId} successfully activated in QuickBooks and Stripe Connect!`);
}

import os
import hmac
import hashlib
from typing import List, Dict, Optional
from fastapi import FastAPI, Request, HTTPException, Header, status
from pydantic import BaseModel, EmailStr
import requests

SIGNBEE_API_URL = "https://api.signb.ee/v1/documents"
SIGNBEE_API_KEY = os.environ.get("SIGNBEE_API_KEY", "")
WEBHOOK_SECRET = os.environ.get("SIGNBEE_WEBHOOK_SECRET", "")

app = FastAPI(title="B2B Vendor Onboarding Engine")

class VendorIntake(BaseModel):
    vendor_id: str
    company_name: str
    signatory_name: str
    signatory_email: EmailStr
    ein: str
    is_high_risk: bool = False

class OnboardingPacketResponse(BaseModel):
    vendor_id: str
    dispatched_documents: List[Dict[str, str]]

def generate_msa_markdown(vendor: VendorIntake) -> str:
    return f"""# MASTER SERVICES AGREEMENT (2026)
**Client:** Apex Cloud Solutions Inc.
**Vendor:** {vendor.company_name} (ID: {vendor.vendor_id})

### 1. Scope & Engagement
Vendor shall render technical and managed consulting services under binding Statements of Work.

### 2. Payment Terms
Invoices submitted by Vendor are payable under Net 30 commercial terms following electronic submission.

### 3. IP Ownership
All work products created specifically for Client shall constitute 'work made for hire' under 17 U.S.C. § 101.
"""

def generate_w9_markdown(vendor: VendorIntake) -> str:
    return f"""# SUBSTITUTE IRS FORM W-9 CERTIFICATION
**Legal Entity:** {vendor.company_name}
**Taxpayer Identification Number (EIN):** {vendor.ein}
**Authorized Agent:** {vendor.signatory_name}

Under penalties of perjury, I certify that the Taxpayer Identification Number listed above is correct,
and I am not subject to IRS backup withholding under 26 U.S.C. § 3406.
"""

@app.post("/v1/vendor/onboard", response_model=OnboardingPacketResponse)
def onboard_vendor(vendor: VendorIntake):
    headers = {
        "Authorization": f"Bearer {SIGNBEE_API_KEY}",
        "Content-Type": "application/json"
    }

    packet_items = [
        {"type": "MSA", "title": f"MSA - {vendor.company_name}", "content": generate_msa_markdown(vendor)},
        {"type": "W9", "title": f"W-9 - {vendor.company_name}", "content": generate_w9_markdown(vendor)},
    ]

    dispatched = []

    for item in packet_items:
        payload = {
            "title": item["title"],
            "content": item["content"],
            "sender_name": "Apex Procurement",
            "sender_email": "procurement@apexcloud.io",
            "recipient_name": vendor.signatory_name,
            "recipient_email": vendor.signatory_email,
            "metadata": {
                "vendor_id": vendor.vendor_id,
                "doc_type": item["type"]
            }
        }

        res = requests.post(SIGNBEE_API_URL, json=payload, headers=headers, timeout=10)
        if not res.ok:
            raise HTTPException(
                status_code=status.HTTP_502_BAD_GATEWAY,
                detail=f"Signbee API error for {item['type']}: {res.text}"
            )

        data = res.json()
        dispatched.append({
            "doc_type": item["type"],
            "document_id": data.get("id"),
            "signing_url": data.get("signing_url")
        })

    return OnboardingPacketResponse(vendor_id=vendor.vendor_id, dispatched_documents=dispatched)

@app.post("/v1/webhooks/signbee")
async def signbee_webhook_listener(
    request: Request,
    x_signbee_signature: Optional[str] = Header(None)
):
    if not x_signbee_signature:
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing signature")

    body_bytes = await request.body()
    
    # Timing-safe HMAC-SHA256 signature verification
    computed_signature = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"),
        body_bytes,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(computed_signature, x_signbee_signature):
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid HMAC signature")

    payload = await request.json()
    event_type = payload.get("event")
    data = payload.get("data", {})

    if event_type == "document.completed":
        doc_id = data.get("id")
        metadata = data.get("metadata", {})
        vendor_id = metadata.get("vendor_id")
        doc_type = metadata.get("doc_type")
        cert_hash = data.get("certificate_hash")

        # Update document record and check if full packet is complete
        process_document_completion(vendor_id, doc_id, doc_type, cert_hash)

    return {"status": "success"}

def process_document_completion(vendor_id: str, doc_id: str, doc_type: str, cert_hash: str):
    # Simulated atomic state aggregation
    print(f"[State Machine] Vendor {vendor_id} finished {doc_type} (Hash: {cert_hash})")
    # If all docs completed -> Provision vendor in ERP and Stripe Connect
    activate_vendor_in_erp(vendor_id)

def activate_vendor_in_erp(vendor_id: str):
    print(f"[ERP Pipeline] Vendor {vendor_id} is 100% verified. Created in QuickBooks and unlocked payouts.")