Upstash Workflow & QStash + Signbee: Guaranteed Serverless E-Signature Delivery (2026)

import { serve } from "@upstash/workflow/nextjs";
import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();

export interface ContractWorkflowPayload {
  orderId: string;
  companyName: string;
  signerName: string;
  signerEmail: string;
  senderName: string;
  senderEmail: string;
  contractValueUsd: number;
}

export interface SignbeeSendApiResult {
  id: string;
  status: "sent" | "pending_verification";
  title: string;
  signing_url: string;
  verify_url: string;
  expires_at: string;
}

export interface SignbeeWebhookEventData {
  document_id: string;
  title: string;
  status: "signed";
  recipient_name: string;
  recipient_email: string;
  signed_at: string;
  sha256_hash: string;
  signed_pdf_url: string;
  verify_url: string;
}

export const { POST } = serve<ContractWorkflowPayload>(
  async (context) => {
    const payload = context.requestPayload;

    // Step 1: Prepare CommonMark contract payload
    const markdownBody = await context.run("compile-contract-markdown", async () => {
      const today = new Date().toISOString().split("T")[0];
      return [
        `# Commercial Service Order — ${payload.companyName}`,
        ``,
        `This Order Form ("Agreement") is effective as of **${today}** between **Acme Edge Inc.** and **${payload.companyName}**.`,
        ``,
        `| Order Reference | Authorized Signer | Total Annual Commitment |`,
        `|---|---|---|`,
        `| ${payload.orderId} | ${payload.signerName} (${payload.signerEmail}) | $${payload.contractValueUsd.toLocaleString()} USD |`,
        ``,
        `### Cryptographic Execution Clause`,
        `Both parties agree that electronic execution sealed with a SHA-256 certificate via Signbee carries the same legal effect as a handwritten signature.`,
      ].join("\n");
    });

    // Step 2: Delegate HTTP POST /api/v1/send directly to QStash via context.call (zero active Lambda wait)
    const { status: httpStatus, body: dispatch } = await context.call<SignbeeSendApiResult>(
      "dispatch-contract-via-signbee",
      {
        url: "https://signb.ee/api/v1/send",
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.SIGNBEE_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: {
          title: `Commercial Order ${payload.orderId} — ${payload.companyName}`,
          markdown: markdownBody,
          sender_name: payload.senderName,
          sender_email: payload.senderEmail,
          recipient_name: payload.signerName,
          recipient_email: payload.signerEmail,
          expires_in_days: 7,
          webhook_url: `${process.env.NEXT_PUBLIC_APP_URL}/api/webhooks/signbee-upstash`,
        },
        retries: 3,
      }
    );

    if (httpStatus < 200 || httpStatus >= 300 || !dispatch?.id) {
      throw new Error(`Signbee dispatch failed with HTTP ${httpStatus}`);
    }

    // Step 3: Suspend workflow for up to 7 days waiting for Signbee document.signed webhook
    const { eventData, timeout } = await context.waitForEvent<SignbeeWebhookEventData>(
      "wait-for-recipient-signature",
      `signbee-signed-${dispatch.id}`,
      { timeout: "7d" }
    );

    // Step 4: Handle 7-day timeout cleanly if recipient never signs
    if (timeout || !eventData) {
      await context.run("handle-expired-contract", async () => {
        await redis.hset(`order:${payload.orderId}`, {
          contractStatus: "EXPIRED",
          documentId: dispatch.id,
          updatedAt: new Date().toISOString(),
        });
      });
      return { outcome: "EXPIRED", documentId: dispatch.id };
    }

    // Step 5: Persist SHA-256 verification hash and unlock customer order
    await context.run("activate-signed-order", async () => {
      await redis.hset(`order:${payload.orderId}`, {
        contractStatus: "SIGNED",
        documentId: eventData.document_id,
        sha256Hash: eventData.sha256_hash,
        signedPdfUrl: eventData.signed_pdf_url,
        verifyUrl: eventData.verify_url,
        signedAt: eventData.signed_at,
      });
    });

    return {
      outcome: "SIGNED_AND_ACTIVATED",
      orderId: payload.orderId,
      documentId: eventData.document_id,
      sha256Hash: eventData.sha256_hash,
    };
  },
  {
    retries: 3,
    failureFunction: async ({ context, failStatus, failResponse }) => {
      // Automatic DLQ & alert hook if downstream activation fails after all retries
      await redis.lpush(
        "dlq:contract-workflows",
        JSON.stringify({
          orderId: context.requestPayload.orderId,
          failStatus,
          failResponse,
          failedAt: new Date().toISOString(),
        })
      );
    },
  }
);

import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";
import { Redis } from "@upstash/redis";
import { Client as WorkflowClient } from "@upstash/workflow";

const redis = Redis.fromEnv();
const workflowClient = new WorkflowClient({
  token: process.env.QSTASH_TOKEN!,
});

function verifySignbeeHmac(rawBody: string, signature: string | null, secret: string): boolean {
  if (!signature) return false;
  const cleanHex = signature.replace(/^sha256=/, "");
  const expectedHex = crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");

  const sigBuf = Buffer.from(cleanHex, "hex");
  const expBuf = Buffer.from(expectedHex, "hex");
  return sigBuf.length === expBuf.length && crypto.timingSafeEqual(sigBuf, expBuf);
}

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

  if (!secret || !verifySignbeeHmac(rawBody, sigHeader, secret)) {
    return NextResponse.json({ error: "Invalid X-Signbee-Signature" }, { status: 401 });
  }

  const payload = JSON.parse(rawBody);
  const documentId: string | undefined = payload?.data?.document_id;

  if (!documentId) {
    return NextResponse.json({ error: "Missing document_id" }, { status: 400 });
  }

  // Atomic Redis SET NX Idempotency Gate (24-hour TTL)
  const idempotencyKey = `idempotency:signbee:${payload.event}:${documentId}`;
  const lockAcquired = await redis.set(idempotencyKey, "PROCESSING", {
    nx: true,
    ex: 86400,
  });

  if (!lockAcquired) {
    // Duplicate webhook delivery detected; acknowledge with 200 OK immediately
    return NextResponse.json({ status: "duplicate_ignored", documentId }, { status: 200 });
  }

  try {
    if (payload.event === "document.signed") {
      await workflowClient.notify({
        eventId: `signbee-signed-${documentId}`,
        eventData: payload.data,
      });
    }

    await redis.set(idempotencyKey, "COMPLETED", { ex: 86400 });
    return NextResponse.json({ status: "notified", documentId }, { status: 200 });
  } catch (err) {
    // Release lock so Signbee's automatic webhook retry can re-attempt delivery
    await redis.del(idempotencyKey);
    throw err;
  }
}

import { Client as QStashClient } from "@upstash/qstash";

const qstash = new QStashClient({
  token: process.env.QSTASH_TOKEN!,
});

/**
 * Buffers an outbound Signbee POST /api/v1/send request through QStash
 * with strict deduplication and automatic exponential backoff.
 */
export async function enqueueGuaranteedSignbeeDispatch(params: {
  orderId: string;
  title: string;
  markdown: string;
  senderName: string;
  senderEmail: string;
  recipientName: string;
  recipientEmail: string;
}) {
  const result = await qstash.publishJSON({
    url: "https://signb.ee/api/v1/send",
    headers: {
      "Authorization": `Bearer ${process.env.SIGNBEE_API_KEY}`,
    },
    body: {
      title: params.title,
      markdown: params.markdown,
      sender_name: params.senderName,
      sender_email: params.senderEmail,
      recipient_name: params.recipientName,
      recipient_email: params.recipientEmail,
      expires_in_days: 7,
      webhook_url: `${process.env.NEXT_PUBLIC_APP_URL}/api/webhooks/signbee-upstash`,
    },
    deduplicationId: `signbee-dispatch-${params.orderId}`,
    retries: 4,
  });

  return { qstashMessageId: result.messageId };
}

/**
 * Inspects and replays any failed messages sitting in the QStash Dead Letter Queue (DLQ)
 * after a downstream database outage is resolved.
 */
export async function replaySignbeeDeadLetterQueue() {
  const dlqResponse = await qstash.dlq.listMessages();
  const replayedIds: string[] = [];

  for (const msg of dlqResponse.messages) {
    await qstash.publish({
      url: msg.url,
      body: msg.body,
      headers: msg.header,
      retries: 3,
    });
    await qstash.dlq.delete(msg.dlqId);
    replayedIds.push(msg.dlqId);
  }

  return { replayedCount: replayedIds.length, replayedIds };
}