xSignwell

A Fastify plugin for integrating with SignWell's e-signature API. Provides document creation, template management, bulk sending, and webhook handling.

Features

• Document Management: Create, send, and track documents for signing
• Template Support: Create and manage reusable document templates
• Embedded Signing: Get URLs for embedded signing experiences
• Bulk Send: Send documents to multiple recipients at once
• Webhooks: Register and manage webhook callbacks for document events
• Test Mode: Built-in support for SignWell's test mode

Installation

npm install xsignwell

Configuration

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | SIGNWELL_API_KEY | SignWell API key | Yes | | SIGNWELL_TEST_MODE | Enable test mode | No |

Plugin Registration

import Fastify from 'fastify';
import xSignwell from 'xsignwell';

const fastify = Fastify();

await fastify.register(xSignwell, {
  apiKey: process.env.SIGNWELL_API_KEY,
  testMode: process.env.NODE_ENV !== 'production',
});

Usage

Documents

Create a Document

const document = await fastify.xsignwell.documents.create({
  name: 'Employment Agreement',
  recipients: [
    {
      id: 'signer_1',
      name: 'John Doe',
      email: '[email protected]',
    },
  ],
  files: [
    {
      name: 'agreement.pdf',
      url: 'https://example.com/agreement.pdf',
      // OR use base64:
      // base64: 'JVBERi0xLjQK...',
    },
  ],
  subject: 'Please sign your employment agreement',
  message: 'Hi John, please review and sign the attached agreement.',
});

Create from Template

const document = await fastify.xsignwell.documents.createFromTemplate(
  'template_id_here',
  {
    recipients: [
      {
        id: 'signer_1', // Must match template recipient ID
        name: 'John Doe',
        email: '[email protected]',
      },
    ],
    fields: {
      employee_name: 'John Doe',
      start_date: '2025-02-01',
      salary: '$75,000',
    },
  }
);

Get Document Status

const document = await fastify.xsignwell.documents.get('document_id');
console.log(document.status); // 'pending', 'completed', etc.

Send a Document

await fastify.xsignwell.documents.send('document_id');

Send Reminder

await fastify.xsignwell.documents.remind('document_id');

Get Completed PDF

const pdf = await fastify.xsignwell.documents.getCompletedPdf('document_id');
// pdf.file_url contains the download URL

Get Embedded Signing URL

const { url, recipient } = await fastify.xsignwell.documents.getEmbeddedSigningUrl(
  'document_id',
  'recipient_id'
);
// Redirect user to `url` for signing

Delete Document

await fastify.xsignwell.documents.remove('document_id');

Templates

Get Template

const template = await fastify.xsignwell.templates.get('template_id');

List Templates

const templates = await fastify.xsignwell.templates.list({
  page: 1,
  limit: 20,
});

Create Template

const template = await fastify.xsignwell.templates.create({
  name: 'NDA Template',
  files: [
    {
      name: 'nda.pdf',
      url: 'https://example.com/nda.pdf',
    },
  ],
  recipients: [
    { id: 'signer_1', name: 'Signer' },
    { id: 'signer_2', name: 'Counter-Signer' },
  ],
});

Update Template

await fastify.xsignwell.templates.update('template_id', {
  name: 'Updated NDA Template',
  subject: 'New subject line',
});

Delete Template

await fastify.xsignwell.templates.remove('template_id');

Get Template Fields

const fields = await fastify.xsignwell.templates.getFields('template_id');

Bulk Send

Create Bulk Send

const bulkSend = await fastify.xsignwell.bulkSend.create({
  templateId: 'template_id',
  recipients: [
    {
      email: '[email protected]',
      name: 'John Doe',
      // Field values for this recipient
      employee_name: 'John Doe',
      start_date: '2025-02-01',
    },
    {
      email: '[email protected]',
      name: 'Jane Smith',
      employee_name: 'Jane Smith',
      start_date: '2025-02-15',
    },
  ],
});

List Bulk Sends

const bulkSends = await fastify.xsignwell.bulkSend.list();

Get Bulk Send Documents

const documents = await fastify.xsignwell.bulkSend.getDocuments('bulk_send_id');

Get CSV Template

const csvTemplate = await fastify.xsignwell.bulkSend.getCsvTemplate('template_id');

Webhooks

List Webhooks

const webhooks = await fastify.xsignwell.webhooks.list();

Create Webhook

const webhook = await fastify.xsignwell.webhooks.create({
  callbackUrl: 'https://your-api.com/webhooks/signwell',
  event: 'document.completed', // Optional: subscribe to specific event
});

Delete Webhook

await fastify.xsignwell.webhooks.remove('webhook_id');

Handle Webhook Events

fastify.post('/webhooks/signwell', async (request, reply) => {
  const event = fastify.xsignwell.webhooks.parseEvent(request.body);

  switch (event.event) {
    case 'document.completed':
      console.log(`Document ${event.documentId} completed`);
      // Download the completed PDF
      const pdf = await fastify.xsignwell.documents.getCompletedPdf(event.documentId);
      break;

    case 'document.signed':
      console.log(`Document ${event.documentId} signed by ${event.recipient?.email}`);
      break;

    case 'document.declined':
      console.log(`Document ${event.documentId} was declined`);
      break;
  }

  return { received: true };
});

Webhook Event Types

const events = fastify.xsignwell.webhooks.events;
// {
//   DOCUMENT_COMPLETED: 'document.completed',
//   DOCUMENT_SENT: 'document.sent',
//   DOCUMENT_VIEWED: 'document.viewed',
//   DOCUMENT_SIGNED: 'document.signed',
//   DOCUMENT_DECLINED: 'document.declined',
//   DOCUMENT_EXPIRED: 'document.expired',
//   DOCUMENT_VOIDED: 'document.voided',
//   RECIPIENT_COMPLETED: 'recipient.completed',
//   RECIPIENT_VIEWED: 'recipient.viewed',
//   RECIPIENT_SIGNED: 'recipient.signed',
//   RECIPIENT_DECLINED: 'recipient.declined',
// }

Account Info

const account = await fastify.xsignwell.me();
console.log(account.email);

API Reference

Decorators

After registration, the following decorators are available on the Fastify instance:

| Decorator | Description | |-----------|-------------| | fastify.xsignwell.documents | Document management methods | | fastify.xsignwell.templates | Template management methods | | fastify.xsignwell.bulkSend | Bulk send methods | | fastify.xsignwell.webhooks | Webhook management methods | | fastify.xsignwell.me | Get account info | | fastify.xsignwell.config | Plugin configuration |

Rate Limits

SignWell API has the following rate limits:

• Standard requests: 100 requests per 60 seconds
• Document creation: 30 requests per minute
• Test mode: 20 requests per minute

Testing

npm test

License

MIT