NestJS E-Signature Integration: Injectable Services, Guards & Webhooks (2026)

// src/main.ts
import { NestFactory } from "@nestjs/core";
import { ValidationPipe } from "@nestjs/common";
import type { NestExpressApplication } from "@nestjs/platform-express";
import { AppModule } from "./app.module";

async function bootstrap() {
  // CRITICAL: Enable rawBody: true so req.rawBody Buffer is populated for HMAC guards
  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
    rawBody: true,
  });

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    })
  );

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

// src/signbee/signbee.config.ts
import { registerAs } from "@nestjs/config";

export default registerAs("signbee", () => ({
  apiKey: process.env.SIGNBEE_API_KEY || "",
  webhookSecret: process.env.SIGNBEE_WEBHOOK_SECRET || "",
  baseUrl: process.env.SIGNBEE_BASE_URL || "https://signb.ee/api/v1",
  senderName: process.env.SIGNBEE_SENDER_NAME || "Apex Fintech Legal",
  senderEmail: process.env.SIGNBEE_SENDER_EMAIL || "agreements@apexfintech.io",
  webhookCallbackUrl:
    process.env.SIGNBEE_WEBHOOK_URL ||
    "https://api.apexfintech.io/v1/webhooks/signbee",
}));

// src/signbee/signbee.service.ts
import {
  Injectable,
  Inject,
  Logger,
  BadGatewayException,
  InternalServerErrorException,
} from "@nestjs/common";
import type { ConfigType } from "@nestjs/config";
import signbeeConfig from "./signbee.config";

export interface DispatchContractInput {
  title: string;
  markdown?: string;
  pdfBase64?: string;
  recipientName: string;
  recipientEmail: string;
  expiresInDays?: number;
}

export interface SignbeeDispatchResult {
  id: string;
  status: "sent" | "pending_verification";
  title: string;
  verify_url: string;
  created_at: string;
}

@Injectable()
export class SignbeeService {
  private readonly logger = new Logger(SignbeeService.name);

  constructor(
    @Inject(signbeeConfig.KEY)
    private readonly config: ConfigType<typeof signbeeConfig>
  ) {
    if (!this.config.apiKey) {
      this.logger.warn("SIGNBEE_API_KEY is not configured in environment");
    }
  }

  async dispatchContract(
    dto: DispatchContractInput
  ): Promise<SignbeeDispatchResult> {
    if (!this.config.apiKey) {
      throw new InternalServerErrorException(
        "Signbee API key is missing from server configuration"
      );
    }

    const response = await fetch(`${this.config.baseUrl}/send`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${this.config.apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        title: dto.title,
        markdown: dto.markdown,
        pdf_base64: dto.pdfBase64,
        sender_name: this.config.senderName,
        sender_email: this.config.senderEmail,
        recipient_name: dto.recipientName,
        recipient_email: dto.recipientEmail,
        expires_in_days: dto.expiresInDays ?? 14,
        webhook_url: this.config.webhookCallbackUrl,
      }),
      signal: AbortSignal.timeout(8000),
    });

    if (!response.ok) {
      const errorPayload = await response.json().catch(() => ({}));
      this.logger.error(
        `Signbee dispatch failed (${response.status}): ${JSON.stringify(errorPayload)}`
      );
      throw new BadGatewayException(
        errorPayload.error || "Upstream e-signature dispatch failed"
      );
    }

    const result = (await response.json()) as SignbeeDispatchResult;
    this.logger.log(
      `Dispatched contract ${result.id} to ${dto.recipientEmail}`
    );
    return result;
  }

  async getDocumentStatus(documentId: string) {
    const response = await fetch(
      `${this.config.baseUrl}/documents/${encodeURIComponent(documentId)}`,
      {
        headers: {
          Authorization: `Bearer ${this.config.apiKey}`,
        },
        signal: AbortSignal.timeout(5000),
      }
    );

    if (!response.ok) {
      throw new BadGatewayException(
        `Unable to fetch status for Signbee document ${documentId}`
      );
    }

    return response.json();
  }
}

// src/signbee/signbee-webhook.guard.ts
import {
  CanActivate,
  ExecutionContext,
  Injectable,
  Inject,
  UnauthorizedException,
} from "@nestjs/common";
import type { RawBodyRequest } from "@nestjs/common";
import type { Request } from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
import type { ConfigType } from "@nestjs/config";
import signbeeConfig from "./signbee.config";

@Injectable()
export class SignbeeWebhookGuard implements CanActivate {
  constructor(
    @Inject(signbeeConfig.KEY)
    private readonly config: ConfigType<typeof signbeeConfig>
  ) {}

  canActivate(context: ExecutionContext): boolean {
    const request = context
      .switchToHttp()
      .getRequest<RawBodyRequest<Request>>();

    const signatureHeader = request.headers["x-signbee-signature"];
    if (!signatureHeader || typeof signatureHeader !== "string") {
      throw new UnauthorizedException("Missing X-Signbee-Signature header");
    }

    if (!request.rawBody || !Buffer.isBuffer(request.rawBody)) {
      throw new UnauthorizedException(
        "Raw request body buffer unavailable; ensure rawBody: true in NestFactory.create"
      );
    }

    const expectedHex = createHmac("sha256", this.config.webhookSecret)
      .update(request.rawBody)
      .digest("hex");

    const cleanProvidedHex = signatureHeader.replace(/^sha256=/, "");
    const providedBuf = Buffer.from(cleanProvidedHex, "hex");
    const expectedBuf = Buffer.from(expectedHex, "hex");

    if (
      providedBuf.length !== expectedBuf.length ||
      !timingSafeEqual(providedBuf, expectedBuf)
    ) {
      throw new UnauthorizedException("Invalid Signbee webhook HMAC signature");
    }

    return true;
  }
}

// src/signbee/signbee-webhook.controller.ts
import {
  Controller,
  Post,
  Body,
  HttpCode,
  HttpStatus,
  UseGuards,
} from "@nestjs/common";
import { InjectQueue } from "@nestjs/bullmq";
import { Queue } from "bullmq";
import { SignbeeWebhookGuard } from "./signbee-webhook.guard";
import { PrismaService } from "../prisma/prisma.service";

interface SignbeeWebhookPayload {
  event: "document.sent" | "document.viewed" | "document.signed" | "document.expired";
  document_id: string;
  title: string;
  recipient_email: string;
  signed_at?: string;
  sha256_hash?: string;
  signed_pdf_url?: string;
  verify_url: string;
}

@Controller("v1/webhooks/signbee")
export class SignbeeWebhookController {
  constructor(
    private readonly prisma: PrismaService,
    @InjectQueue("contract-fulfillment") private readonly fulfillmentQueue: Queue
  ) {}

  @Post()
  @HttpCode(HttpStatus.OK)
  @UseGuards(SignbeeWebhookGuard)
  async handleWebhook(@Body() payload: SignbeeWebhookPayload) {
    if (payload.event === "document.signed") {
      // Atomic idempotent conditional update: only transition if not already SIGNED
      const updated = await this.prisma.contractRecord.updateMany({
        where: {
          signbeeDocumentId: payload.document_id,
          status: { not: "SIGNED" },
        },
        data: {
          status: "SIGNED",
          sha256CertificateHash: payload.sha256_hash,
          signedPdfUrl: payload.signed_pdf_url,
          verifyUrl: payload.verify_url,
          signedAt: payload.signed_at ? new Date(payload.signed_at) : new Date(),
        },
      });

      // Only enqueue downstream fulfillment once even if webhook is delivered twice
      if (updated.count > 0) {
        await this.fulfillmentQueue.add(
          "provision-signed-tenant",
          {
            documentId: payload.document_id,
            recipientEmail: payload.recipient_email,
            sha256Hash: payload.sha256_hash,
          },
          {
            jobId: `signbee-${payload.document_id}-${payload.event}`,
            attempts: 5,
            backoff: { type: "exponential", delay: 2000 },
          }
        );
      }
    }

    return { received: true, documentId: payload.document_id };
  }
}