HubSpot CRM Custom Code Workflows for E-Signatures via API (2026)

const hubspot = require('@hubspot/api-client');

exports.main = async (event, callback) => {
  // 1. Retrieve environment secrets
  const SIGNBEE_API_KEY = process.env.SIGNBEE_API_KEY;
  const HUBSPOT_ACCESS_TOKEN = process.env.HUBSPOT_ACCESS_TOKEN;

  if (!SIGNBEE_API_KEY) {
    throw new Error("Missing SIGNBEE_API_KEY secret in HubSpot Workflow.");
  }

  // 2. Extract deal properties passed into the action
  const {
    hs_object_id: dealId,
    dealname,
    amount,
    pipeline,
    dealstage
  } = event.inputFields;

  const hubspotClient = new hubspot.Client({ accessToken: HUBSPOT_ACCESS_TOKEN });

  // 3. Fetch associated Contact (Primary Signer) and Company
  let signerEmail = "";
  let signerName = "Authorized Representative";
  let companyName = "Client Organization";

  try {
    const associations = await hubspotClient.crm.deals.associationsApi.getAll(dealId, 'contacts');
    if (associations.results && associations.results.length > 0) {
      const contactId = associations.results[0].id;
      const contactRecord = await hubspotClient.crm.contacts.basicApi.getById(contactId, ['email', 'firstname', 'lastname']);
      
      signerEmail = contactRecord.properties.email;
      const first = contactRecord.properties.firstname || "";
      const last = contactRecord.properties.lastname || "";
      signerName = `${first} ${last}`.trim() || signerName;
    }

    const companyAssoc = await hubspotClient.crm.deals.associationsApi.getAll(dealId, 'companies');
    if (companyAssoc.results && companyAssoc.results.length > 0) {
      const companyId = companyAssoc.results[0].id;
      const companyRecord = await hubspotClient.crm.companies.basicApi.getById(companyId, ['name']);
      companyName = companyRecord.properties.name || companyName;
    }
  } catch (err) {
    console.warn("Association lookup warning (fallback used):", err.message);
  }

  if (!signerEmail) {
    throw new Error(`Cannot dispatch contract: No contact email found for Deal ID ${dealId}`);
  }

  // Format currency
  const formattedAmount = Number(amount || 0).toLocaleString('en-US', {
    style: 'currency',
    currency: 'USD'
  });

  const currentDate = new Date().toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  });

  // 4. Construct dynamic Markdown contract template
  const markdownContract = `# SOFTWARE SERVICE AGREEMENT

**Effective Date:** ${currentDate}  
**Agreement Reference:** HUB-${dealId}

---

### PARTIES
This Software Service Agreement ("Agreement") is entered into by and between:
1. **Provider:** Acme Cloud Technologies Inc., a Delaware corporation ("Provider").
2. **Customer:** ${companyName}, represented by ${signerName} ("Customer").

---

### 1. SERVICES & COMMITMENT
Provider agrees to deliver enterprise platform capabilities as outlined in Deal "${dealname}". Customer agrees to pay the contract value detailed below.

| Description | Contract Value | Payment Term | Billing Cycle |
| :--- | :--- | :--- | :--- |
| **Enterprise Platform Access** | ${formattedAmount} | Net 30 | Annual Upfront |

### 2. TERM & TERMINATION
This Agreement shall commence on the Effective Date and continue for an initial term of twelve (12) months. Either party may terminate with 30 days written notice prior to renewal.

### 3. GOVERNING LAW & SIGNATURES
This agreement shall be governed by the laws of the State of Delaware. The parties acknowledge and agree that electronic signatures executed through this interface comply with the ESIGN Act and UETA regulations.

---

**CUSTOMER ACCEPTANCE:**  
**Company:** ${companyName}  
**Signer Name:** ${signerName}  
**Email:** ${signerEmail}
`;

  // 5. Dispatch to Signbee REST API
  const signbeeResponse = await fetch("https://api.signb.ee/v1/documents", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${SIGNBEE_API_KEY}`
    },
    body: JSON.stringify({
      title: `Contract: ${dealname} - ${companyName}`,
      markdown: markdownContract,
      signers: [
        {
          name: signerName,
          email: signerEmail,
          role: "signer"
        }
      ],
      metadata: {
        hubspot_deal_id: dealId,
        company_name: companyName,
        deal_amount: amount
      },
      require_consent: true,
      expires_in_days: 14
    })
  });

  if (!signbeeResponse.ok) {
    const errorText = await signbeeResponse.text();
    throw new Error(`Signbee API dispatch failed (${signbeeResponse.status}): ${errorText}`);
  }

  const signbeeData = await signbeeResponse.json();

  // 6. Return output fields back to the HubSpot Workflow
  callback({
    outputFields: {
      signbee_document_id: signbeeData.id,
      signing_url: signbeeData.signing_url || "",
      signature_status: "pending"
    }
  });
};

import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";

const SIGNBEE_WEBHOOK_SECRET = process.env.SIGNBEE_WEBHOOK_SECRET!;
const HUBSPOT_ACCESS_TOKEN = process.env.HUBSPOT_ACCESS_TOKEN!;

// Contract Signed Deal Stage ID in your HubSpot Pipeline
const HUBSPOT_STAGE_CONTRACT_SIGNED = "contract_signed"; 

function verifyHmacSignature(rawBody: string, signatureHeader: string | null): boolean {
  if (!signatureHeader || !SIGNBEE_WEBHOOK_SECRET) return false;

  const expectedSignature = crypto
    .createHmac("sha256", SIGNBEE_WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, "utf8"),
    Buffer.from(signatureHeader, "utf8")
  );
}

export async function POST(req: NextRequest) {
  try {
    const rawBody = await req.text();
    const signature = req.headers.get("x-signbee-signature");

    // 1. Verify Webhook Authenticity
    if (!verifyHmacSignature(rawBody, signature)) {
      return NextResponse.json({ error: "Invalid HMAC signature" }, { status: 401 });
    }

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

    // We only process completed document executions
    if (event !== "document.completed") {
      return NextResponse.json({ received: true, ignored: true });
    }

    const dealId = data.metadata?.hubspot_deal_id;
    if (!dealId) {
      console.warn("No hubspot_deal_id found in document metadata:", data.id);
      return NextResponse.json({ received: true, warning: "Missing deal ID" });
    }

    const downloadUrl = data.download_url;
    const sha256Hash = data.sha256;
    const completedAt = data.completed_at || new Date().toISOString();

    // 2. Update HubSpot Deal via CRM v3 REST API
    const hubspotUrl = `https://api.hubapi.com/crm/v3/objects/deals/${dealId}`;
    const updateResponse = await fetch(hubspotUrl, {
      method: "PATCH",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${HUBSPOT_ACCESS_TOKEN}`
      },
      body: JSON.stringify({
        properties: {
          dealstage: HUBSPOT_STAGE_CONTRACT_SIGNED,
          signature_status: "signed",
          contract_pdf_url: downloadUrl,
          contract_signed_date: completedAt
        }
      })
    });

    if (!updateResponse.ok) {
      const err = await updateResponse.text();
      console.error(`Failed to update HubSpot deal ${dealId}:`, err);
      return NextResponse.json({ error: "HubSpot update failed" }, { status: 500 });
    }

    // 3. Create an engagement Note on the Deal timeline
    await fetch("https://api.hubapi.com/crm/v3/objects/notes", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${HUBSPOT_ACCESS_TOKEN}`
      },
      body: JSON.stringify({
        properties: {
          hs_timestamp: new Date().toISOString(),
          hs_note_body: `✅ **Contract Executed Electronically**<br/><br/>` +
            `• **Signbee Doc ID:** ${data.id}<br/>` +
            `• **Audit SHA-256:** `${sha256Hash}`<br/>` +
            `• **Download PDF:** <a href="${downloadUrl}" target="_blank">View Executed PDF</a>`
        },
        associations: [
          {
            to: { id: dealId },
            types: [
              {
                associationCategory: "HUBSPOT_DEFINED",
                associationTypeId: 214 // Note to Deal association
              }
            ]
          }
        ]
      })
    });

    return NextResponse.json({ success: true, dealId });
  } catch (error: any) {
    console.error("Webhook processing error:", error);
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
}

// Fetch line items associated with Deal
const lineItemsResponse = await hubspotClient.crm.deals.associationsApi.getAll(dealId, 'line_items');
let lineItemMarkdown = "| Item | Qty | Unit Price | Total |\n| :--- | :--- | :--- | :--- |\n";

for (const item of lineItemsResponse.results) {
  const itemDetails = await hubspotClient.crm.lineItems.basicApi.getById(item.id, ['name', 'quantity', 'price', 'amount']);
  const { name, quantity, price, amount } = itemDetails.properties;
  
  lineItemMarkdown += `| ${name} | ${quantity} | $${price} | $${amount} |\n`;
}