fix(documenso): align webhook receiver with Documenso v1.13 + 2.x protocol

Documenso authenticates outbound webhooks via the X-Documenso-Secret
header carrying the plaintext secret (no HMAC). The previous receiver
verified an HMAC against a non-existent x-documenso-signature header
and switched on parsed.type, neither of which Documenso emits — so
every real delivery was being silently rejected.

- Read X-Documenso-Secret, compare timing-safe to env secret
- Switch on parsed.event with uppercase normalization for both v1.13
  (DOCUMENT_SIGNED) and 2.x (lowercase-dotted UI labels) wire formats
- Alias DOCUMENT_RECIPIENT_COMPLETED to DOCUMENT_SIGNED (same
  semantics across versions)
- Handle DOCUMENT_OPENED / DOCUMENT_REJECTED / DOCUMENT_CANCELLED in
  addition to the existing DOCUMENT_SIGNED + DOCUMENT_COMPLETED paths
- Bypass session middleware for /api/webhooks/* (signature is the auth)

Verified end-to-end against signatures.letsbe.solutions: real
DOCUMENT_RECIPIENT_COMPLETED + DOCUMENT_COMPLETED deliveries now pass
secret verification, dispatch correctly, and the handler updates
state (or warns gracefully when the documensoId is unknown).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/webhooks/documenso/route.ts

@@ -2,11 +2,13 @@ import { NextRequest, NextResponse } from 'next/server';
 import { createHash } from 'crypto';
 
 import { db } from '@/lib/db';
-import { verifyDocumensoSignature } from '@/lib/services/documenso-webhook';
+import { verifyDocumensoSecret } from '@/lib/services/documenso-webhook';
 import {
   handleRecipientSigned,
   handleDocumentCompleted,
-  handleDocumentExpired,
+  handleDocumentOpened,
+  handleDocumentRejected,
+  handleDocumentCancelled,
 } from '@/lib/services/documents.service';
 import { env } from '@/lib/env';
 import { logger } from '@/lib/logger';
@@ -14,39 +16,58 @@ import { logger } from '@/lib/logger';
 // BR-024: Dedup via signatureHash unique index on documentEvents
 // Always return 200 from webhook (webhook best practice)
 
+// Documenso emits Prisma enum names on the wire (e.g. "DOCUMENT_SIGNED").
+// The UI displays them as lowercase-dotted ("document.signed") but the JSON
+// body uses the enum value as-is. Normalize both forms in case 2.x ever flips.
+function canonicalizeEvent(event: string): string {
+  return event.toUpperCase().replace(/\./g, '_');
+}
+
+type DocumensoRecipient = {
+  email: string;
+  signingStatus?: string;
+  readStatus?: string;
+  signedAt?: string | null;
+};
+
+type DocumensoWebhookBody = {
+  event: string;
+  payload: {
+    id: number | string;
+    recipients?: DocumensoRecipient[];
+  };
+};
+
 export async function POST(req: NextRequest): Promise<NextResponse> {
-  let payload: string;
+  let rawBody: string;
 
   try {
-    payload = await req.text();
+    rawBody = await req.text();
   } catch {
     return NextResponse.json({ ok: false }, { status: 200 });
   }
 
-  // Verify HMAC signature
-  const signature = req.headers.get('x-documenso-signature') ?? '';
+  // Documenso v1.13 + 2.x send the secret in plaintext via X-Documenso-Secret.
+  const providedSecret = req.headers.get('x-documenso-secret') ?? '';
 
-  if (!verifyDocumensoSignature(payload, signature, env.DOCUMENSO_WEBHOOK_SECRET)) {
-    logger.warn({ signature }, 'Invalid Documenso webhook signature');
-    return NextResponse.json({ ok: false, error: 'Invalid signature' }, { status: 200 });
+  if (!verifyDocumensoSecret(providedSecret, env.DOCUMENSO_WEBHOOK_SECRET)) {
+    logger.warn({ providedLen: providedSecret.length }, 'Invalid Documenso webhook secret');
+    return NextResponse.json({ ok: false, error: 'Invalid secret' }, { status: 200 });
   }
 
   // Compute deduplication hash
-  const signatureHash = createHash('sha256').update(payload).digest('hex');
+  const signatureHash = createHash('sha256').update(rawBody).digest('hex');
 
-  let parsed: { type: string; payload: Record<string, unknown> };
+  let parsed: DocumensoWebhookBody;
 
   try {
-    parsed = JSON.parse(payload) as typeof parsed;
+    parsed = JSON.parse(rawBody) as DocumensoWebhookBody;
   } catch {
     logger.warn('Failed to parse Documenso webhook payload');
     return NextResponse.json({ ok: false }, { status: 200 });
   }
 
-  // Dedup: try to insert a sentinel documentEvent with signatureHash
-  // We need a documentId — if dedup fails at this stage we can't easily check.
-  // Instead, store the hash lookup on the first real documentEvent insert in handlers.
-  // Here we just check if this hash was already seen in any event.
+  // Replay guard: if any event with this hash already exists, skip.
   try {
     const existing = await db.query.documentEvents.findFirst({
       where: (de, { eq }) => eq(de.signatureHash, signatureHash),
@@ -60,33 +81,69 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
     logger.error({ err }, 'Failed to check duplicate webhook');
   }
 
+  const event = canonicalizeEvent(parsed.event);
+  const documensoId = String(parsed.payload?.id ?? '');
+  const recipients = parsed.payload?.recipients ?? [];
+
+  if (!documensoId) {
+    logger.warn({ event }, 'Documenso webhook missing payload.id');
+    return NextResponse.json({ ok: true }, { status: 200 });
+  }
+
   try {
-    switch (parsed.type) {
-      case 'RECIPIENT_SIGNED':
-        await handleRecipientSigned({
-          documentId: parsed.payload.documentId as string,
-          recipientEmail: parsed.payload.recipientEmail as string,
+    switch (event) {
+      case 'DOCUMENT_SIGNED':
+      case 'DOCUMENT_RECIPIENT_COMPLETED': {
+        // v1.13 fires DOCUMENT_SIGNED per recipient sign;
+        // 2.x fires DOCUMENT_RECIPIENT_COMPLETED for the same semantics.
+        const signedRecipients = recipients.filter(
+          (r) => r.signingStatus === 'SIGNED' || Boolean(r.signedAt),
+        );
+        for (const r of signedRecipients) {
+          await handleRecipientSigned({
+            documentId: documensoId,
+            recipientEmail: r.email,
+            signatureHash: `${signatureHash}:signed:${r.email}`,
+          });
+        }
+        break;
+      }
+
+      case 'DOCUMENT_OPENED': {
+        const openedRecipients = recipients.filter((r) => r.readStatus === 'OPENED');
+        for (const r of openedRecipients) {
+          await handleDocumentOpened({
+            documentId: documensoId,
+            recipientEmail: r.email,
+            signatureHash: `${signatureHash}:opened:${r.email}`,
+          });
+        }
+        break;
+      }
+
+      case 'DOCUMENT_COMPLETED':
+        await handleDocumentCompleted({ documentId: documensoId });
+        break;
+
+      case 'DOCUMENT_REJECTED': {
+        const rejecting = recipients.find((r) => r.signingStatus === 'REJECTED');
+        await handleDocumentRejected({
+          documentId: documensoId,
+          recipientEmail: rejecting?.email,
           signatureHash,
         });
         break;
+      }
 
-      case 'DOCUMENT_COMPLETED':
-        await handleDocumentCompleted({
-          documentId: parsed.payload.documentId as string,
-        });
-        break;
-
-      case 'DOCUMENT_EXPIRED':
-        await handleDocumentExpired({
-          documentId: parsed.payload.documentId as string,
-        });
+      case 'DOCUMENT_CANCELLED':
+        await handleDocumentCancelled({ documentId: documensoId, signatureHash });
         break;
 
       default:
-        logger.info({ type: parsed.type }, 'Unhandled Documenso webhook event type');
+        logger.info({ event }, 'Unhandled Documenso webhook event type');
     }
   } catch (err) {
-    logger.error({ err, type: parsed.type }, 'Error processing Documenso webhook');
+    logger.error({ err, event }, 'Error processing Documenso webhook');
   }
 
   return NextResponse.json({ ok: true }, { status: 200 });