How to Automate Contract Signing in Your App

curl -X POST https://signb.ee/api/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Service Agreement\n\nThis agreement is between **Acme Corp** and **Jane Doe** for design consulting services at $150/hour.\n\n## Scope\n\n- Brand identity design\n- Website mockups (3 rounds)\n- Final asset delivery in Figma\n\n## Terms\n\n- Net 30 payment terms\n- Valid for 6 months from signing",
    "senderName": "Michael Chen",
    "senderEmail": "michael@acmecorp.com",
    "recipientName": "Jane Doe",
    "recipientEmail": "jane@studio.com"
  }'

const response = await fetch('https://signb.ee/api/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: `# Service Agreement

This agreement is between **Acme Corp** and **Jane Doe**
for design consulting at $150/hour.

## Scope
- Brand identity design
- Website mockups (3 rounds)
- Final asset delivery in Figma

## Terms
- Net 30 payment terms
- Valid for 6 months`,
    senderName: 'Michael Chen',
    senderEmail: 'michael@acmecorp.com',
    recipientName: 'Jane Doe',
    recipientEmail: 'jane@studio.com',
  }),
});

const result = await response.json();
// { id: "doc_abc123", status: "pending" }

import requests

response = requests.post(
    'https://signb.ee/api/send',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'content': '# Service Agreement\n\nThis agreement...',
        'senderName': 'Michael Chen',
        'senderEmail': 'michael@acmecorp.com',
        'recipientName': 'Jane Doe',
        'recipientEmail': 'jane@studio.com',
    }
)

print(response.json())

const response = await fetch('https://signb.ee/api/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pdf_url: 'https://your-app.com/contracts/template-v2.pdf',
    senderName: 'Michael Chen',
    senderEmail: 'michael@acmecorp.com',
    recipientName: 'Jane Doe',
    recipientEmail: 'jane@studio.com',
  }),
});

// When a client approves a contractor's proposal
async function onProposalAccepted(proposal) {
  // Generate the contract from your template
  const contract = generateContract({
    clientName: proposal.client.name,
    clientEmail: proposal.client.email,
    contractorName: proposal.contractor.name,
    contractorEmail: proposal.contractor.email,
    rate: proposal.hourlyRate,
    scope: proposal.scopeDescription,
  });

  // Send for signing — one API call
  const result = await fetch('https://signb.ee/api/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SIGNBEE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content: contract,
      senderName: proposal.client.name,
      senderEmail: proposal.client.email,
      recipientName: proposal.contractor.name,
      recipientEmail: proposal.contractor.email,
    }),
  });

  // Update your database
  await db.proposals.update({
    where: { id: proposal.id },
    data: {
      status: 'contract_sent',
      contractId: (await result.json()).id,
    },
  });
}

const status = await fetch(
  `https://signb.ee/api/documents/${documentId}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

const doc = await status.json();
// doc.status: "pending" | "sender_signed" | "completed"
// doc.certificateUrl: signed PDF (when completed)

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

enum DocumentStatus {
  DRAFT
  PENDING
  COMPLETED
  DECLINED
  EXPIRED
}

enum SignerStatus {
  INACTIVE
  ACTIVE
  SIGNED
  DECLINED
}

model Document {
  id             String         @id @default(uuid())
  title          String
  fileKey        String         @unique
  status         DocumentStatus @default(PENDING)
  metadata       Json?
  createdAt      DateTime       @default(now())
  updatedAt      DateTime       @updatedAt
  signers        Signer[]

  @@index([status])
}

model Signer {
  id             String       @id @default(uuid())
  documentId     String
  document       Document     @relation(fields: [documentId], references: [id], onDelete: Cascade)
  name           String
  email          String
  signingOrder   Int
  status         SignerStatus @default(INACTIVE)
  signedAt       DateTime?
  token          String       @unique
  expiresAt      DateTime
  createdAt      DateTime     @default(now())
  updatedAt      DateTime     @updatedAt

  @@unique([documentId, signingOrder])
  @@index([status, email])
  @@index([token])
}

from sqlalchemy import Column, String, Integer, DateTime, Enum, ForeignKey, UniqueConstraint, Index, JSON
from sqlalchemy.orm import declarative_base, relationship
from datetime import datetime
import enum

Base = declarative_base()

class DocumentStatus(enum.Enum):
    DRAFT = "DRAFT"
    PENDING = "PENDING"
    COMPLETED = "COMPLETED"
    DECLINED = "DECLINED"
    EXPIRED = "EXPIRED"

class SignerStatus(enum.Enum):
    INACTIVE = "INACTIVE"
    ACTIVE = "ACTIVE"
    SIGNED = "SIGNED"
    DECLINED = "DECLINED"

class Document(Base):
    __tablename__ = "documents"

    id = Column(String(36), primary_key=True, index=True)
    title = Column(String(255), nullable=False)
    file_key = Column(String(255), unique=True, nullable=False)
    status = Column(Enum(DocumentStatus), default=DocumentStatus.PENDING, nullable=False)
    metadata_json = Column(JSON, nullable=True)
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)

    signers = relationship("Signer", back_populates="document", cascade="all, delete-orphan")

    __table_args__ = (
        Index("idx_document_status", "status"),
    )

class Signer(Base):
    __tablename__ = "signers"

    id = Column(String(36), primary_key=True, index=True)
    document_id = Column(String(36), ForeignKey("documents.id", ondelete="CASCADE"), nullable=False)
    name = Column(String(255), nullable=False)
    email = Column(String(255), nullable=False)
    signing_order = Column(Integer, nullable=False)
    status = Column(Enum(SignerStatus), default=SignerStatus.INACTIVE, nullable=False)
    signed_at = Column(DateTime, nullable=True)
    token = Column(String(255), unique=True, nullable=False)
    expires_at = Column(DateTime, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)

    document = relationship("Document", back_populates="signers")

    __table_args__ = (
        UniqueConstraint("document_id", "signing_order", name="uq_document_signer_order"),
        Index("idx_signer_status_email", "status", "email"),
        Index("idx_signer_token", "token"),
    )

import express from 'express';
import crypto from 'crypto';
import { Queue, Worker } from 'bullmq';
import IORedis from 'ioredis';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();
const connection = new IORedis(process.env.REDIS_URL || 'redis://127.0.0.1:6379');

// Initialize BullMQ Queue
const signingQueue = new Queue('signature-events', { connection });

const app = express();
app.use(express.json({
  verify: (req: any, res, buf) => {
    req.rawBody = buf;
  }
}));

const WEBHOOK_SECRET = process.env.SIGNBEE_WEBHOOK_SECRET || 'super-secret-key';

// Webhook endpoint to receive Signbee completion hooks
app.post('/webhooks/signbee', async (req: any, res) => {
  const signature = req.headers['signbee-signature'];
  if (!signature || typeof signature !== 'string') {
    return res.status(401).json({ error: 'Missing signature header' });
  }

  // Verify HMAC-SHA256 signature
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  hmac.update(req.rawBody);
  const expectedSignature = hmac.digest('hex');

  try {
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  } catch (err) {
    return res.status(401).json({ error: 'Signature verification failed' });
  }

  const event = req.body;
  
  if (event.type === 'document.signer.signed') {
    await signingQueue.add('process-signer-completion', {
      documentId: event.data.documentId,
      signerEmail: event.data.signerEmail,
      signedAt: event.data.signedAt,
    });
  }

  return res.status(200).json({ received: true });
});

// BullMQ Worker to process events in the background asynchronously
const worker = new Worker('signature-events', async (job) => {
  const { documentId, signerEmail, signedAt } = job.data;

  // Execute inside a database transaction to prevent race conditions
  await prisma.$transaction(async (tx) => {
    // 1. Find the current signer
    const currentSigner = await tx.signer.findFirst({
      where: {
        documentId,
        email: signerEmail,
        status: 'ACTIVE',
      },
    });

    if (!currentSigner) {
      console.log(`Signer ${signerEmail} not found or already processed for doc ${documentId}`);
      return;
    }

    // 2. Mark the current signer as SIGNED
    await tx.signer.update({
      where: { id: currentSigner.id },
      data: {
        status: 'SIGNED',
        signedAt: new Date(signedAt),
      },
    });

    // 3. Find the next signer in sequential order (currentOrder + 1)
    const nextSigner = await tx.signer.findFirst({
      where: {
        documentId,
        signingOrder: currentSigner.signingOrder + 1,
      },
    });

    if (nextSigner) {
      // 4. Update next signer status to ACTIVE
      await tx.signer.update({
        where: { id: nextSigner.id },
        data: { status: 'ACTIVE' },
      });

      // 5. Trigger POST to Signbee to dispatch the signing link to Signer 2
      const signbeeResponse = await fetch('https://signb.ee/api/v1/send', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.SIGNBEE_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          pdf_url: `https://your-app-bucket.s3.amazonaws.com/contracts/${documentId}.pdf`,
          senderName: 'Contract Workflow System',
          senderEmail: 'noreply@yourdomain.com',
          recipientName: nextSigner.name,
          recipientEmail: nextSigner.email,
          metadata: {
            documentId: documentId,
            signingOrder: nextSigner.signingOrder,
          },
        }),
      });

      if (!signbeeResponse.ok) {
        throw new Error(`Failed to dispatch signing link to next signer ${nextSigner.email}`);
      }
    } else {
      // No next signer exists — the document is fully executed
      await tx.document.update({
        where: { id: documentId },
        data: { status: 'COMPLETED' },
      });

      console.log(`Document ${documentId} is fully signed by all parties.`);
    }
  });
}, { connection });

import hmac
import hashlib
import os
from flask import Flask, request, jsonify, abort
from celery import Celery
from database import db_session
from models import Document, Signer, DocumentStatus, SignerStatus
from datetime import datetime
import requests

app = Flask(__name__)

# Configure Celery
app.config['CELERY_BROKER_URL'] = os.getenv('REDIS_URL', 'redis://localhost:6379/0')
celery = Celery(app.name, broker=app.config['CELERY_BROKER_URL'])
celery.conf.update(app.config)

WEBHOOK_SECRET = os.getenv('SIGNBEE_WEBHOOK_SECRET', 'super-secret-key').encode('utf-8')

def verify_webhook_signature(data: bytes, signature: str) -> bool:
    if not signature:
        return False
    expected = hmac.new(WEBHOOK_SECRET, data, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/webhooks/signbee', methods=['POST'])
def signbee_webhook():
    signature = request.headers.get('Signbee-Signature')
    raw_body = request.get_data()

    if not verify_webhook_signature(raw_body, signature):
        abort(401, description="Invalid webhook signature")

    event = request.json
    if event.get('type') == 'document.signer.signed':
        process_signer_completion.delay(
            document_id=event['data']['documentId'],
            signer_email=event['data']['signerEmail'],
            signed_at_str=event['data']['signedAt']
        )

    return jsonify({"received": True}), 200

@celery.task(bind=True, max_retries=3, default_retry_delay=10)
def process_signer_completion(self, document_id: str, signer_email: str, signed_at_str: str):
    session = db_session()
    try:
        with session.begin():
            # 1. Retrieve current signer in ACTIVE state
            current_signer = session.query(Signer).filter(
                Signer.document_id == document_id,
                Signer.email == signer_email,
                Signer.status == SignerStatus.ACTIVE
            ).first()

            if not current_signer:
                print(f"Signer {signer_email} not active or already processed for doc {document_id}")
                return

            # 2. Update status to SIGNED
            current_signer.status = SignerStatus.SIGNED
            current_signer.signed_at = datetime.fromisoformat(signed_at_str.replace('Z', '+00:00'))

            # 3. Find next signer in line
            next_signer = session.query(Signer).filter(
                Signer.document_id == document_id,
                Signer.signing_order == current_signer.signing_order + 1
            ).first()

            if next_signer:
                # 4. Activate the next signer
                next_signer.status = SignerStatus.ACTIVE

                # 5. Dispatch API POST request to Signbee
                payload = {
                    "pdf_url": f"https://your-app-bucket.s3.amazonaws.com/contracts/{document_id}.pdf",
                    "senderName": "Contract Workflow System",
                    "senderEmail": "noreply@yourdomain.com",
                    "recipientName": next_signer.name,
                    "recipientEmail": next_signer.email,
                    "metadata": {
                        "documentId": document_id,
                        "signingOrder": next_signer.signing_order
                    }
                }
                
                response = requests.post(
                    "https://signb.ee/api/v1/send",
                    json=payload,
                    headers={
                        "Authorization": f"Bearer {os.getenv('SIGNBEE_API_KEY')}",
                        "Content-Type": "application/json"
                    },
                    timeout=10
                )

                if response.status_code != 200:
                    raise Exception(f"Signbee API error: {response.text}")
            else:
                # No next signer — update document to completed
                document = session.query(Document).filter(Document.id == document_id).first()
                if document:
                    document.status = DocumentStatus.COMPLETED
                    print(f"Document {document_id} fully signed.")
    except Exception as exc:
        session.rollback()
        raise self.retry(exc=exc)
    finally:
        session.close()