Temporal.io + Signbee: Durable Contract Signing Workflows in TypeScript (2026)

import { Context, ApplicationFailure } from "@temporalio/activity";

export interface DispatchContractInput {
  customerId: string;
  title: string;
  markdown: string;
  senderName: string;
  senderEmail: string;
  recipientName: string;
  recipientEmail: string;
  expiresInDays: number;
  revisionNumber: number;
}

export interface DispatchContractResult {
  documentId: string;
  status: string;
  signingUrl: string;
  verifyUrl: string;
  expiresAt: string;
}

export async function dispatchSignbeeContractActivity(
  input: DispatchContractInput
): Promise<DispatchContractResult> {
  const ctx = Context.current();
  const { workflowId } = ctx.info.workflowExecution;
  const idempotencyKey = `${workflowId}-rev-${input.revisionNumber}`;

  const apiKey = process.env.SIGNBEE_API_KEY;
  const webhookUrl = process.env.SIGNBEE_WEBHOOK_URL;
  if (!apiKey || !webhookUrl) {
    throw ApplicationFailure.nonRetryable(
      "Missing SIGNBEE_API_KEY or SIGNBEE_WEBHOOK_URL in Worker environment",
      "ConfigurationError"
    );
  }

  const response = await fetch("https://signb.ee/api/v1/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      title: input.title,
      markdown: input.markdown,
      sender_name: input.senderName,
      sender_email: input.senderEmail,
      recipient_name: input.recipientName,
      recipient_email: input.recipientEmail,
      expires_in_days: input.expiresInDays,
      webhook_url: webhookUrl,
      metadata: {
        temporal_workflow_id: workflowId,
        customer_id: input.customerId,
        revision: String(input.revisionNumber),
      },
    }),
  });

  if (response.status >= 400 && response.status < 500 && response.status !== 429) {
    const errorBody = await response.text();
    // 4xx validation errors should not be retried by Temporal
    throw ApplicationFailure.nonRetryable(
      `Signbee 4xx rejection (${response.status}): ${errorBody}`,
      "SignbeeValidationError"
    );
  }

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`Transient Signbee HTTP ${response.status}: ${errorBody}`);
  }

  const data = (await response.json()) as {
    id: string;
    status: string;
    signing_url: string;
    verify_url: string;
    expires_at: string;
  };

  return {
    documentId: data.id,
    status: data.status,
    signingUrl: data.signing_url,
    verifyUrl: data.verify_url,
    expiresAt: data.expires_at,
  };
}

export async function sendSigningReminderActivity(params: {
  recipientEmail: string;
  recipientName: string;
  signingUrl: string;
  reminderAttempt: number;
}): Promise<void> {
  Context.current().log.info("Sending contract reminder nudge", params);
  // Dispatch reminder via Resend, Slack, or WhatsApp
}

export async function provisionEnterpriseTenantActivity(params: {
  customerId: string;
  signbeeDocumentId: string;
  sha256Hash: string;
}): Promise<{ tenantId: string }> {
  Context.current().log.info("Provisioning enterprise account post-signature", params);
  return { tenantId: `tenant_${params.customerId}` };
}

export async function releaseReservedCreditHoldActivity(params: {
  customerId: string;
  reason: string;
}): Promise<void> {
  Context.current().log.warn("Executing Saga compensation: releasing credit hold", params);
}

import {
  proxyActivities,
  defineSignal,
  defineQuery,
  setHandler,
  condition,
} from "@temporalio/workflow";
import type * as activities from "../activities/signbee-activities";

const {
  dispatchSignbeeContractActivity,
  sendSigningReminderActivity,
  provisionEnterpriseTenantActivity,
  releaseReservedCreditHoldActivity,
} = proxyActivities<typeof activities>({
  startToCloseTimeout: "30 seconds",
  retry: {
    initialInterval: "2 seconds",
    backoffCoefficient: 2.0,
    maximumInterval: "30 seconds",
    maximumAttempts: 5,
  },
});

export interface SignbeeWebhookSignalPayload {
  documentId: string;
  event: "document.signed" | "document.declined" | "document.expired" | "document.viewed";
  sha256Hash?: string;
  signedPdfUrl?: string;
  verifyUrl?: string;
  signedAt?: string;
}

export const contractWebhookSignal = defineSignal<[SignbeeWebhookSignalPayload]>(
  "signbeeContractWebhook"
);

export const contractStateQuery = defineQuery<{
  status: string;
  documentId: string | null;
  signingUrl: string | null;
  remindersSent: number;
  sha256Hash: string | null;
}>("getContractWorkflowState");

export async function enterpriseContractOnboardingWorkflow(input: {
  customerId: string;
  title: string;
  markdown: string;
  senderName: string;
  senderEmail: string;
  recipientName: string;
  recipientEmail: string;
}): Promise<{ status: string; tenantId?: string; sha256Hash?: string }> {
  const state = {
    status: "PENDING" as "PENDING" | "SIGNED" | "DECLINED" | "EXPIRED",
    documentId: null as string | null,
    signingUrl: null as string | null,
    remindersSent: 0,
    sha256Hash: null as string | null,
  };

  setHandler(contractStateQuery, () => state);

  setHandler(contractWebhookSignal, (payload) => {
    // Ignore stale signals from older contract revisions
    if (state.documentId && payload.documentId !== state.documentId) {
      return;
    }
    if (payload.event === "document.signed") {
      state.status = "SIGNED";
      state.sha256Hash = payload.sha256Hash ?? null;
    } else if (payload.event === "document.declined") {
      state.status = "DECLINED";
    } else if (payload.event === "document.expired") {
      state.status = "EXPIRED";
    }
  });

  // Step 1: Dispatch contract via Signbee REST API Activity
  const dispatchResult = await dispatchSignbeeContractActivity({
    ...input,
    expiresInDays: 7,
    revisionNumber: 1,
  });

  state.documentId = dispatchResult.documentId;
  state.signingUrl = dispatchResult.signingUrl;

  // Step 2: Durable human wait loop with 48-hour reminders (max 3 reminders = 6 days)
  const maxReminderCycles = 3;
  for (let cycle = 1; cycle <= maxReminderCycles; cycle++) {
    const resolvedBeforeTimeout = await condition(
      () => state.status !== "PENDING",
      "48 hours"
    );

    if (resolvedBeforeTimeout) {
      break;
    }

    // Still PENDING after 48 hours -> trigger reminder Activity
    await sendSigningReminderActivity({
      recipientEmail: input.recipientEmail,
      recipientName: input.recipientName,
      signingUrl: dispatchResult.signingUrl,
      reminderAttempt: cycle,
    });
    state.remindersSent = cycle;
  }

  // Step 3: Evaluate outcome or run Saga compensation
  if (state.status !== "SIGNED" || !state.sha256Hash) {
    await releaseReservedCreditHoldActivity({
      customerId: input.customerId,
      reason: `Contract ended in status: ${state.status}`,
    });
    return { status: state.status };
  }

  // Step 4: Contract cryptographically signed -> provision tenant
  const { tenantId } = await provisionEnterpriseTenantActivity({
    customerId: input.customerId,
    signbeeDocumentId: dispatchResult.documentId,
    sha256Hash: state.sha256Hash,
  });

  return {
    status: "SIGNED",
    tenantId,
    sha256Hash: state.sha256Hash,
  };
}

import { NextRequest, NextResponse } from "next/server";
import crypto from "node:crypto";
import { Connection, Client } from "@temporalio/client";
import { contractWebhookSignal } from "@/temporal/workflows/contract-signing.workflow";

function verifySignbeeSignature(
  rawBody: string,
  signatureHeader: string | null,
  secret: string
): boolean {
  if (!signatureHeader) return false;
  const cleanHex = signatureHeader.replace(/^sha256=/, "").trim();

  const expectedHex = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  const a = Buffer.from(cleanHex, "utf8");
  const b = Buffer.from(expectedHex, "utf8");
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

let cachedTemporalClient: Client | null = null;
async function getTemporalClient(): Promise<Client> {
  if (cachedTemporalClient) return cachedTemporalClient;
  const connection = await Connection.connect({
    address: process.env.TEMPORAL_ADDRESS ?? "localhost:7233",
  });
  cachedTemporalClient = new Client({
    connection,
    namespace: process.env.TEMPORAL_NAMESPACE ?? "default",
  });
  return cachedTemporalClient;
}

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

  if (!verifySignbeeSignature(rawBody, signature, secret)) {
    return NextResponse.json({ error: "Invalid HMAC signature" }, { status: 401 });
  }

  const body = JSON.parse(rawBody) as {
    event: "document.signed" | "document.declined" | "document.expired" | "document.viewed";
    document_id: string;
    sha256_hash?: string;
    signed_pdf_url?: string;
    verify_url?: string;
    signed_at?: string;
    metadata?: { temporal_workflow_id?: string };
  };

  const workflowId = body.metadata?.temporal_workflow_id;
  if (!workflowId) {
    return NextResponse.json({ received: true, skipped: "No temporal_workflow_id" });
  }

  const temporal = await getTemporalClient();
  const handle = temporal.workflow.getHandle(workflowId);

  await handle.signal(contractWebhookSignal, {
    documentId: body.document_id,
    event: body.event,
    sha256Hash: body.sha256_hash,
    signedPdfUrl: body.signed_pdf_url,
    verifyUrl: body.verify_url,
    signedAt: body.signed_at,
  });

  return NextResponse.json({ received: true, signaledWorkflowId: workflowId });
}