WeGoSignWeGoSign
API Documentation

WeGoSign API Documentation

Integrate document signing into your applications with our powerful REST API. Send documents for signature, track progress, and automate your workflows.

Quickstart

Send your first document in 5 minutes

Authentication

Learn how to authenticate API requests

Webhooks

Receive real-time event notifications

Getting Started

Everything you need to integrate WeGoSign into your application

Introduction

The WeGoSign API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Secure

All API requests are made over HTTPS with SHA-256 hashed API keys

Fast

Average response time under 200ms for most operations

RESTful

Standard REST conventions with predictable resource URLs

Idempotent

Safe to retry requests without creating duplicates

Base URL

https://wegosign.com/api/v1

Quickstart

Send your first document for signature in just a few steps:

1

Get your API key

Navigate to your organization settings in the dashboard and create a new API key.

API keys start with wgs_live_ for production or wgs_test_ for testing.

2

Create a template

Upload a PDF and define signature fields via the dashboard or API.

curl -X POST https://wegosign.com/api/v1/templates \
  -H "Authorization: Bearer wgs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Contract",
    "description": "Standard employment agreement",
    "document": {
      "data": "base64_encoded_pdf_content",
      "filename": "contract.pdf"
    }
  }'
3

Send for signature

Create an envelope with your template and specify the signers.

curl -X POST https://wegosign.com/api/v1/envelopes \
  -H "Authorization: Bearer wgs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "template_id_from_step_2",
    "title": "Employment Contract - John Doe",
    "message": "Please review and sign the attached contract.",
    "signers": [
      {
        "name": "John Doe",
        "email": "john@example.com",
        "role": "signer"
      }
    ]
  }'
4

Done!

The signer receives an email with a link to sign the document. You can track progress via the API or webhooks.

Authentication

The WeGoSign API uses API keys to authenticate requests. You can create and manage API keys from your organization settings in the dashboard.

API Key Format

wgs_live_*

Production keys for live transactions

wgs_test_*

Test keys for development and testing

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

Example Request
curl https://wegosign.com/api/v1/templates \
  -H "Authorization: Bearer wgs_live_your_api_key"

Alternative: X-API-Key Header

If your platform strips Authorization headers (common with some serverless environments), you can use theX-API-Key header as a fallback:

X-API-Key: wgs_live_your_api_key

Keep your API keys secure

Never expose API keys in client-side code or public repositories. Store them securely in environment variables.

API Reference

Complete reference for all API endpoints

Templates

Templates are reusable document definitions with pre-configured signature fields. Upload a PDF, define where signatures should go, and reuse it for multiple envelopes.

GET
/api/v1/templates

List Templates

Retrieves all templates for your organization.

Query Parameters

include_archived
boolean(default: false)

Include archived templates in the response

Response

Response
{
  "data": [
    {
      "id": "tpl_abc123",
      "name": "Employment Contract",
      "description": "Standard employment agreement",
      "pageCount": 3,
      "fieldCount": 5,
      "roles": ["employee", "employer"],
      "isArchived": false,
      "createdAt": 1704543600000,
      "updatedAt": 1704543600000
    }
  ]
}
POST
/api/v1/templates

Create Template

Creates a new template by uploading a PDF document. Optionally include fields with conditional logic.

Request Body

Template creation payload with base64-encoded PDF and optional fields

Request
{
  "name": "Employment Contract",
  "description": "Standard employment agreement",
  "document": {
    "data": "base64_encoded_pdf_content",
    "filename": "contract.pdf"
  },
  "fields": [
    {
      "id": "field_1",
      "type": "signature",
      "role": "employee",
      "page": 1,
      "x": 100,
      "y": 500,
      "width": 200,
      "height": 50,
      "required": true,
      "label": "Employee Signature"
    },
    {
      "id": "field_2",
      "type": "dropdown",
      "role": "employee",
      "page": 1,
      "x": 100,
      "y": 300,
      "width": 150,
      "height": 30,
      "required": true,
      "label": "Department",
      "options": [
        { "label": "Engineering", "value": "eng" },
        { "label": "Sales", "value": "sales" }
      ]
    }
  ]
}

Response

Returns the created template with field count and roles.

Response
{
  "data": {
    "id": "tpl_abc123",
    "name": "Employment Contract",
    "description": "Standard employment agreement",
    "documentName": "contract.pdf",
    "fieldCount": 2,
    "roles": ["employee"],
    "createdAt": 1704543600000
  }
}
PATCH
/api/v1/templates/{id}/fields

Update Template Fields

Updates all fields for a template. Supports all field types and conditional logic.

Request Body

Array of fields with positions, types, and optional conditions

Request
{
  "fields": [
    {
      "id": "field_1",
      "type": "dropdown",
      "role": "signer",
      "page": 1,
      "x": 100,
      "y": 200,
      "width": 150,
      "height": 30,
      "required": true,
      "label": "Select Option",
      "options": [
        { "label": "Option A", "value": "a" },
        { "label": "Option B", "value": "b" }
      ]
    },
    {
      "id": "field_2",
      "type": "text",
      "role": "signer",
      "page": 1,
      "x": 100,
      "y": 250,
      "width": 200,
      "height": 30,
      "required": false,
      "label": "Additional Details",
      "conditions": [
        {
          "sourceFieldId": "field_1",
          "operator": "equals",
          "value": "b"
        }
      ],
      "conditionAction": "show",
      "conditionLogic": "all"
    }
  ]
}

Response

Returns the updated field count and roles.

Response
{
  "data": {
    "id": "tpl_abc123",
    "fieldCount": 2,
    "roles": ["signer"],
    "updatedAt": 1704543600000
  }
}
GET
/api/v1/templates/{id}/fields

Get Template Fields

Retrieves all fields for a template including their conditions.

Response

Returns all fields, roles, and placeholder keys for the template.

Response
{
  "data": {
    "templateId": "tpl_abc123",
    "fields": [
      {
        "id": "field_1",
        "type": "dropdown",
        "role": "signer",
        "page": 1,
        "x": 100,
        "y": 200,
        "width": 150,
        "height": 30,
        "required": true,
        "label": "Select Option",
        "options": [
          { "label": "Option A", "value": "a" },
          { "label": "Option B", "value": "b" }
        ]
      }
    ],
    "roles": ["signer"],
    "placeholderKeys": []
  }
}

Envelopes

Envelopes represent documents sent for signature. Create an envelope from a template, specify one or more signers, and track the signing progress.

Envelope Status Lifecycle

draft
sent
viewed
completed

Multiple Signers & Signing Order

Sequential Signing

Signers sign one after another. Use different signingOrder values (1, 2, 3...). Signer 2 can only sign after Signer 1 completes.

Parallel Signing

All signers can sign simultaneously. Use the same signingOrder value for all signers (e.g., all set to 1).

GET
/api/v1/envelopes

List Envelopes

Retrieves all envelopes for your organization with optional filtering.

Query Parameters

status
string

Filter by status: draft, sent, viewed, signed, completed, declined, cancelled, expired

limit
number(default: 50)

Number of results per page

Response

Response
{
  "data": [
    {
      "id": "env_xyz789",
      "title": "Employment Contract - John Doe",
      "status": "sent",
      "templateName": "Employment Contract",
      "signers": [
        {
          "id": "sgn_abc123",
          "name": "John Doe",
          "email": "john@example.com",
          "role": "employee",
          "status": "pending"
        }
      ],
      "createdAt": 1704543600000,
      "completedAt": null,
      "expiresAt": 1705148400000
    }
  ]
}
POST
/api/v1/envelopes

Create & Send Envelope

Creates a new envelope from a template with one or more signers. Supports sequential or parallel signing.

Query Parameters

signers
required
array

Array of signers. Each signer needs name, email. Optional: role, signingOrder (for sequential signing), redirectUrl.

signers[].signingOrder
number(default: 1)

Order in which signers sign. Same number = parallel signing. Different numbers = sequential (1 signs first, then 2, etc.).

scheduledAt
string (ISO 8601)

Schedule envelope to be sent at a future time. Must be 5 min to 30 days in the future. Omit to send immediately.

Request Body

Envelope creation payload with multiple signers

Request
{
  "templateId": "tpl_abc123",
  "title": "Employment Contract - John Doe",
  "message": "Please review and sign the attached contract.",
  "expiresInHours": 168,
  "scheduledAt": "2026-01-15T09:00:00Z",
  "signers": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "employee",
      "signingOrder": 1,
      "redirectUrl": "https://yourapp.com/signed"
    },
    {
      "name": "Jane Smith",
      "email": "jane@company.com",
      "role": "employer",
      "signingOrder": 2
    },
    {
      "name": "Legal Team",
      "email": "legal@company.com",
      "role": "approver",
      "signingOrder": 3
    }
  ]
}

Response

Returns envelope ID and unique signing URLs for each signer. Status is 'scheduled' if scheduledAt provided, otherwise 'sent'.

Response
{
  "data": {
    "id": "env_xyz789",
    "status": "scheduled",
    "scheduledAt": "2026-01-15T09:00:00.000Z",
    "signers": [
      {
        "id": "sgn_abc123",
        "email": "john@example.com",
        "signingUrl": "https://wegosign.com/sign/abc123..."
      },
      {
        "id": "sgn_def456",
        "email": "jane@company.com",
        "signingUrl": "https://wegosign.com/sign/def456..."
      },
      {
        "id": "sgn_ghi789",
        "email": "legal@company.com",
        "signingUrl": "https://wegosign.com/sign/ghi789..."
      }
    ]
  }
}
GET
/api/v1/envelopes/:id

Get Envelope

Retrieves detailed information about a specific envelope.

Path Parameters

id
required
string

The envelope ID

Response

Response
{
  "data": {
    "id": "env_xyz789",
    "title": "Employment Contract - John Doe",
    "status": "completed",
    "createdAt": 1704543600000,
    "sentAt": 1704543610000,
    "completedAt": 1704630000000,
    "expiresAt": 1705148400000
  }
}
DELETE
/api/v1/envelopes/:id

Cancel Envelope

Cancels an envelope. Only envelopes in 'sent' status can be cancelled.

Path Parameters

id
required
string

The envelope ID

Response

Response
{
  "data": {
    "id": "env_xyz789",
    "status": "cancelled"
  }
}
POST
/api/v1/envelopes/:id/remind

Send Reminder

Sends a reminder email to signers who haven't completed signing.

Path Parameters

id
required
string

The envelope ID

Request Body

Optional parameters for the reminder

Request
{
  "signerId": "sgn_abc123",
  "message": "Friendly reminder to sign the document."
}

Response

Response
{
  "data": {
    "success": true,
    "remindedCount": 1
  }
}
GET
/api/v1/envelopes/:id/audit-log

Get Audit Log

Retrieves the complete audit trail for an envelope showing all actions.

Query Parameters

limit
number(default: 100)

Number of records to return

Path Parameters

id
required
string

The envelope ID

Response

Response
{
  "data": [
    {
      "id": "log_1",
      "action": "envelope_created",
      "actionDescription": "Envelope created",
      "actorType": "api",
      "actorEmail": "admin@company.com",
      "ipAddress": "192.168.1.1",
      "timestamp": 1704543600000
    },
    {
      "id": "log_2",
      "action": "document_viewed",
      "actionDescription": "Document viewed by signer",
      "actorType": "signer",
      "actorEmail": "john@example.com",
      "ipAddress": "203.0.113.50",
      "timestamp": 1704550000000
    }
  ]
}
GET
/api/v1/envelopes/:id/download

Download Signed Document

Retrieves download URLs for the signed PDF document and certificate. Only available for completed envelopes.

Query Parameters

type
string(default: all)

What to download: 'document', 'certificate', or 'all'

Path Parameters

id
required
string

The envelope ID

Response

Download URLs expire after 1 hour. Request new URLs if they have expired.

Response
{
  "data": {
    "id": "env_xyz789",
    "title": "Employment Contract - John Doe",
    "status": "completed",
    "completedAt": 1704630000000,
    "documentUrl": "https://storage.convex.cloud/...",
    "certificateUrl": "https://storage.convex.cloud/...",
    "expiresIn": "1 hour"
  }
}

Signers

Signers are the recipients of an envelope who need to sign the document. Track individual signer progress and status.

GET
/api/v1/envelopes/:id/signers

Get Envelope Signers

Retrieves all signers for an envelope with their current status.

Path Parameters

id
required
string

The envelope ID

Response

Response
{
  "data": [
    {
      "id": "sgn_abc123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "employee",
      "signingOrder": 1,
      "status": "signed",
      "viewedAt": 1704550000000,
      "signedAt": 1704560000000,
      "declinedAt": null,
      "declineReason": null,
      "reminderSentAt": null
    }
  ]
}

Bulk Sends

Send documents to multiple recipients at once. Perfect for onboarding, mass communications, or any scenario requiring the same document sent to many people. Supports column mapping for placeholders and prefilled fields, scheduled sends, and error reporting.

Growth Plan & Above
POST
/api/v1/bulk-sends

Create Bulk Send

Creates and initiates a bulk send operation for multiple recipients. Supports column mappings for document placeholders and prefilled signer fields, as well as scheduled sends.

Request Body

Bulk send creation payload

Request
{
  "templateId": "tpl_abc123",
  "titlePrefix": "Onboarding Document",
  "message": "Welcome! Please sign your onboarding documents.",
  "expiresInHours": 168,
  "recipients": [
    {
      "email": "john@example.com",
      "name": "John Doe",
      "role": "employee",
      "additionalData": {
        "company": "Acme Inc",
        "start_date": "2024-02-01",
        "employee_id": "EMP-001"
      }
    },
    {
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "employee",
      "additionalData": {
        "company": "Acme Inc",
        "start_date": "2024-02-15",
        "employee_id": "EMP-002"
      }
    }
  ],
  "columnMappings": {
    "placeholders": {
      "company": "company_name",
      "start_date": "employment_start_date"
    },
    "signerFields": {
      "employee_id": "field_employee_id"
    }
  },
  "scheduledAt": 1704600000000
}

Response

Bulk sends are processed asynchronously. If scheduledAt is provided, status will be 'scheduled' and processing will begin at that time. Column mappings allow mapping recipient additionalData to document placeholders or prefillable signer fields.

Response
{
  "data": {
    "id": "bulk_abc123",
    "totalRecipients": 2,
    "status": "scheduled",
    "scheduledAt": 1704600000000,
    "message": "Bulk send scheduled for 2024-01-07T08:00:00.000Z"
  }
}
GET
/api/v1/bulk-sends/:id

Get Bulk Send Status

Retrieves the status and results of a bulk send operation, including all created envelopes.

Path Parameters

id
required
string

The bulk send ID

Response

Response
{
  "data": {
    "id": "bulk_abc123",
    "templateId": "tpl_abc123",
    "templateName": "Employment Contract",
    "status": "completed",
    "totalRecipients": 2,
    "processedCount": 2,
    "successCount": 2,
    "failureCount": 0,
    "errors": [],
    "columnMappings": {
      "placeholders": { "company": "company_name" },
      "signerFields": { "employee_id": "field_employee_id" }
    },
    "scheduledAt": null,
    "createdAt": 1704543600000,
    "completedAt": 1704543700000,
    "envelopes": [
      {
        "id": "env_xyz789",
        "title": "Onboarding Document - John Doe",
        "status": "sent",
        "placeholderValues": [
          { "key": "company_name", "value": "Acme Inc" }
        ],
        "signers": [
          {
            "email": "john@example.com",
            "status": "sent",
            "prefilledFields": { "field_employee_id": "EMP-001" }
          }
        ]
      }
    ]
  }
}
GET
/api/v1/bulk-sends/:id/errors

Get Error Report

Retrieves a detailed error report for a bulk send. Useful for identifying which recipients failed and why. Supports JSON and CSV formats.

Path Parameters

id
required
string

The bulk send ID

format
string

Response format: 'json' (default) or 'csv'

Response

Use ?format=csv to download errors as a CSV file for easy analysis in spreadsheets.

Response
{
  "data": {
    "bulkSendId": "bulk_abc123",
    "templateId": "tpl_abc123",
    "titlePrefix": "Onboarding Document",
    "status": "completed",
    "summary": {
      "totalRecipients": 10,
      "successCount": 8,
      "failureCount": 2
    },
    "createdAt": 1704543600000,
    "completedAt": 1704543700000,
    "errors": [
      {
        "row": 5,
        "email": "invalid@example",
        "errorType": "invalid_data",
        "errorMessage": "Invalid email format"
      },
      {
        "row": 8,
        "email": "quota@example.com",
        "errorType": "quota_exceeded",
        "errorMessage": "Monthly envelope limit reached"
      }
    ]
  }
}
DELETE
/api/v1/bulk-sends/:id

Cancel Bulk Send

Cancels a bulk send operation and all its associated pending envelopes. Scheduled bulk sends can also be cancelled before they start processing.

Path Parameters

id
required
string

The bulk send ID

Response

Returns the number of envelopes that were cancelled. Completed bulk sends cannot be cancelled.

Response
{
  "data": {
    "id": "bulk_abc123",
    "cancelled": true,
    "cancelledEnvelopes": 5
  }
}

Bulk Send Webhook Events

Subscribe to these webhook events to track bulk send progress:

  • bulk_send.started - Fired when bulk send processing begins
  • bulk_send.completed - Fired when all envelopes have been processed
  • bulk_send.failed - Fired when bulk send fails (all recipients failed)

Webhooks

Receive real-time notifications when events occur in your account. Configure webhook endpoints to automate workflows and keep your systems in sync.

Growth Plan & Above
POST
/api/v1/webhooks

Create Webhook

Creates a new webhook endpoint to receive event notifications.

Request Body

Webhook configuration

Request
{
  "url": "https://yourapp.com/webhooks/wegosign",
  "events": [
    "envelope.created",
    "envelope.sent",
    "envelope.completed",
    "signer.viewed",
    "signer.signed",
    "signer.declined",
    "document.downloaded"
  ],
  "description": "Main production webhook"
}

Response

The webhook secret is only shown once on creation. Store it securely for signature verification.

Response
{
  "data": {
    "id": "whk_abc123",
    "url": "https://yourapp.com/webhooks/wegosign",
    "events": ["envelope.created", "envelope.completed", "signer.signed"],
    "description": "Main production webhook",
    "secret": "whsec_abc123xyz789...",
    "isActive": true,
    "createdAt": 1704543600000
  }
}
GET
/api/v1/webhooks

List Webhooks

Retrieves all webhooks configured for your organization.

Response

Response
{
  "data": [
    {
      "id": "whk_abc123",
      "url": "https://yourapp.com/webhooks/wegosign",
      "events": ["envelope.completed", "signer.signed"],
      "description": "Main production webhook",
      "isActive": true,
      "failureCount": 0,
      "lastDeliveredAt": 1704550000000,
      "createdAt": 1704543600000
    }
  ]
}
GET
/api/v1/webhooks/:id

Get Webhook

Retrieves a specific webhook by its ID.

Path Parameters

id
required
string

The webhook ID

Response

Response
{
  "data": {
    "id": "whk_abc123",
    "url": "https://yourapp.com/webhooks/wegosign",
    "events": ["envelope.completed", "signer.signed"],
    "description": "Main production webhook",
    "isActive": true,
    "failureCount": 0,
    "lastDeliveredAt": 1704550000000,
    "createdAt": 1704543600000
  }
}
DELETE
/api/v1/webhooks/:id

Delete Webhook

Permanently deletes a webhook endpoint.

Path Parameters

id
required
string

The webhook ID

Response

Response
{
  "data": {
    "id": "whk_abc123",
    "deleted": true
  }
}
Guides

In-depth guides for common use cases

Document Signing Flow

Understanding the complete lifecycle of a document from creation to completion.

1

Create Template

Upload a PDF and define signature fields via the dashboard or API. Templates are reusable and can be used for multiple envelopes.

2

Create & Send Envelope

Create an envelope from a template and specify signers. Each signer receives a unique, secure signing link via email.

3

Signer Views Document

When a signer clicks their link, they can view the document and see where they need to sign. This triggers the 'signer.viewed' webhook.

4

Signer Completes Signing

The signer fills in required fields and signs. They can draw, type, or upload a signature. This triggers 'signer.signed'.

5

Document Completed

When all signers complete, the envelope status changes to 'completed'. Download the signed PDF with embedded audit trail.

Basic Field Types

signature

Full signature - draw, type, or upload

initials

Quick initials field

sender_signature

Sender pre-signs before sending

date

Auto-filled date field

text

Free-form text input

checkbox

Checkbox for acknowledgments

Advanced Field Types

email

Email address with validation

phone

Phone number with country code

number

Numeric input with min/max validation

dropdown

Single-select dropdown menu

radio_group

Radio buttons - select one option

multi_select

Checkboxes - select multiple options

date_picker

Calendar date picker for custom dates

Conditional Field Logic

Show, hide, or require fields based on other field values. Configure conditions in the template editor.

Supported Operators:

• equals - Value matches exactly
• not_equals - Value does not match
• contains - Value contains text
• not_contains - Value does not contain text
• is_empty - Field is empty
• is_not_empty - Field has a value
• greater_than / less_than - Numeric comparison

Actions:

• Show - Display field when conditions are met
• Hide - Hide field when conditions are met
• Require - Make field required when conditions are met

Sequential Signing

Control the order in which signers must sign documents. Sequential signing ensures that signers can only access and sign the document when it's their turn.

How It Works

1. Assign a signingOrder number to each signer (1 = first)

2. Signers with lower numbers must complete before higher numbers can access the document

3. Signers attempting to access out of order receive a "not your turn" message

API Example

Sequential signing request
{
  "templateId": "template_abc123",
  "signers": [
    { "name": "Manager", "email": "manager@company.com", "signingOrder": 1 },
    { "name": "Director", "email": "director@company.com", "signingOrder": 2 },
    { "name": "CEO", "email": "ceo@company.com", "signingOrder": 3 }
  ]
}

Parallel Signing

For parallel signing where all signers can sign simultaneously, assign the samesigningOrder to all signers or omit it entirely.

Template Packages

Template packages allow you to bundle multiple templates together for complex multi-document signing workflows. Signers receive all documents in a single signing session.

Key Features

Multi-Document Bundles

Combine multiple templates into a single package

Unified Role Mapping

Map package roles to template-specific roles

Single Signing Session

Signers complete all documents in one session

Consistent Experience

Same signer sees their fields across all docs

Dashboard Only

Template packages are currently managed through the dashboard. API support for creating and managing packages is coming soon.

Scheduled Sends

Schedule envelopes to be sent at a future date and time. Perfect for time-sensitive documents or coordinating across time zones.

API Example

Scheduled envelope request
{
  "templateId": "template_abc123",
  "signers": [
    { "name": "John Doe", "email": "john@example.com" }
  ],
  "scheduledAt": "2024-12-15T09:00:00Z"
}

Constraints

• Minimum: Must be at least 5 minutes in the future

• Maximum: Cannot be more than 30 days in the future

• Format: ISO 8601 timestamp (e.g., 2024-12-15T09:00:00Z)

Bulk Send Scheduling

Bulk sends also support scheduling. Include scheduledAtin your bulk send request to schedule mass document delivery.

CC Recipients

Add CC (carbon copy) recipients to receive copies of the envelope without needing to sign. They're notified when the envelope is sent and completed.

API Example

Envelope with CC recipients
{
  "templateId": "template_abc123",
  "signers": [
    { "name": "John Doe", "email": "john@example.com" }
  ],
  "ccRecipients": [
    { "name": "Legal Team", "email": "legal@company.com" },
    { "name": "HR Manager", "email": "hr@company.com" }
  ]
}

CC vs Signers

FeatureSignersCC Recipients
Can sign document✓—
Notified when sent✓✓
Notified when completed✓✓
Receives signed document✓✓

Password Protection

Add an extra layer of security by requiring signers to enter a password before viewing and signing documents. Available on all plans.

Key Features

Per-Signer Passwords

Each signer has their own unique password

Auto-Generated

8-character alphanumeric passwords by default

Multi-Channel Delivery

Deliver via Email, SMS, or WhatsApp

Lockout Protection

Account locked after 5 failed attempts

Security Flow

1. Sender enables password protection for a signer

2. Password is auto-generated (or custom-set) and delivered via chosen channel

3. Signer must enter correct password before viewing the document

4. After 5 failed attempts, access is locked until sender resends password

Dashboard Only

Password protection is currently configured through the dashboard when creating envelopes. API support for password-protected envelopes is planned for a future release.

Webhook Events

WeGoSign sends webhook notifications for the following events:

Envelope Events

envelope.created

An envelope has been created

envelope.sent

An envelope has been sent to signers

envelope.viewed

Any signer has viewed the document

envelope.signed

Any signer has completed their signature

envelope.completed

All signers have completed signing

envelope.declined

Any signer has declined to sign

envelope.cancelled

An envelope has been cancelled

envelope.expired

An envelope has expired without completion

Signer Events

signer.viewed

A specific signer has viewed the document

signer.signed

A specific signer has completed signing

signer.declined

A specific signer has declined to sign

Reminder Events

reminder.sent

A reminder email was sent to a signer (automatic or manual)

Document Events

document.downloaded

A signed document has been downloaded

Bulk Send Events

bulk_send.started

A bulk send job has started processing

bulk_send.completed

A bulk send job has finished successfully

bulk_send.failed

A bulk send job has failed

Webhook Payload Structure

Example Webhook Payload (signer.signed event)
{
  "id": "evt_abc123xyz",
  "type": "signer.signed",
  "created": 1704543600000,
  "data": {
    "envelope": {
      "id": "env_xyz789",
      "title": "Employment Contract - John Doe",
      "status": "signed",
      "createdAt": 1704543600000,
      "completedAt": null
    },
    "signer": {
      "id": "sgn_abc123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "employee",
      "status": "signed",
      "viewedAt": 1704543500000,
      "signedAt": 1704543600000,
      "declinedAt": null,
      "declineReason": null,
      "completedFields": [
        {
          "fieldId": "field_signature_1",
          "value": "data:image/png;base64,iVBORw0KGgoAAA...",
          "completedAt": 1704543590000
        },
        {
          "fieldId": "field_email_1",
          "value": "john.doe@example.com",
          "completedAt": 1704543580000
        },
        {
          "fieldId": "field_dropdown_1",
          "value": "Full-Time",
          "completedAt": 1704543570000
        }
      ]
    },
    "timestamp": 1704543600000
  }
}

Verifying Webhook Signatures

Verify that webhooks are actually from WeGoSign by checking the signature header:

Signature Verification (Node.js)
1import crypto from 'crypto';
2
3function verifyWebhookSignature(payload, signature, timestamp, secret) {
4  // Signature format is "sha256=<hex>"
5  const signatureHex = signature.replace('sha256=', '');
6
7  // Create message: timestamp.payload
8  const message = `${timestamp}.${payload}`;
9
10  const expectedSignature = crypto
11    .createHmac('sha256', secret)
12    .update(message)
13    .digest('hex');
14
15  return crypto.timingSafeEqual(
16    Buffer.from(signatureHex),
17    Buffer.from(expectedSignature)
18  );
19}
20
21// In your webhook handler
22app.post('/webhooks/wegosign', (req, res) => {
23  const signature = req.headers['x-webhook-signature'];
24  const timestamp = req.headers['x-webhook-timestamp'];
25  const eventType = req.headers['x-webhook-event'];
26
27  const isValid = verifyWebhookSignature(
28    JSON.stringify(req.body),
29    signature,
30    timestamp,
31    process.env.WEBHOOK_SECRET
32  );
33
34  if (!isValid) {
35    return res.status(401).send('Invalid signature');
36  }
37
38  // Access payload fields: id, type, created, data
39  const { id, type, created, data } = req.body;
40  console.log('Processing event:', type, 'Event ID:', id);
41
42  // Process the webhook based on event type...
43  res.status(200).send('OK');
44});

Error Handling

The API uses standard HTTP status codes and returns error details in a consistent format.

Error Response Format

Error Response
{
  "error": "validation_error",
  "message": "Invalid email format for signer",
  "details": {
    "field": "signers[0].email",
    "value": "invalid-email"
  }
}

HTTP Status Codes

200

Success - Request completed successfully

201

Created - Resource created successfully

400

Bad Request - Invalid request parameters

401

Unauthorized - Invalid or missing API key

403

Forbidden - Insufficient permissions

404

Not Found - Resource doesn't exist

429

Too Many Requests - Rate limit exceeded

500

Server Error - Something went wrong on our end

Rate Limits

API rate limits vary by plan and operation type. Rate limit information is included in response headers.

Rate Limit Headers

X-RateLimit-Limit

Maximum requests allowed in the window

X-RateLimit-Remaining

Requests remaining in current window

X-RateLimit-Reset

Unix timestamp when the limit resets

Retry-After

Seconds to wait before retrying (429 responses only)

Limits by Plan

Ready to get started?

Create your free account and get API keys to start integrating document signing today.

Contact Support