Introduction
Electronic signatures have transformed how businesses handle agreements, contracts, and approvals. What once required printing, scanning, and mailing now happens in seconds through well-designed API integrations. Dropbox Sign offers what many consider the industry's fastest eSignature API, with documented cases showing document completion up to 80% faster than traditional methods. For modern web applications built with Next.js, integrating eSignature capabilities opens doors to streamlined workflows, reduced friction, and improved conversion rates.
This guide walks through implementing HelloSign's API in a modern web development context, focusing on performance, security, and user experience. Whether you're building a contract management system, onboarding flow, or sales agreement process, you'll find practical patterns for embedding secure, legally-binding e-signatures directly into your application.
What You'll Learn
- API Authentication and Setup - OAuth 2.0 implementation, API key management, and test mode configuration
- Core API Endpoints - Signature requests, templates, and team management with comprehensive code examples
- Embedded Signing Experience - Keeping users on your site throughout the signing process for seamless UX
- Webhook Implementation - Real-time notifications for document events and workflow automation
- Performance Optimization - Caching strategies, request batching, and CDN utilization for high-volume applications
- Security Best Practices - API key rotation, HTTPS enforcement, input validation, and webhook security
- Next.js Integration Patterns - Server Actions, API routes, and React Server Components for modern applications
Key capabilities that make HelloSign the industry leader for developer eSignature implementations
API-First Design
RESTful API with comprehensive endpoints for signature requests, templates, team management, and webhooks
Embedded Signing
Keep users on your site throughout the signing process with fully customizable embedded experiences
Test Mode
Complete development testing without legal signatures--test entire workflows safely before production
Comprehensive SDKs
Official libraries for JavaScript, Python, Ruby, PHP, and .NET with type definitions
Real-Time Webhooks
Instant notifications for document events--viewing, signing, completion, and more
Compliance Built-In
ESIGN, UETA, and eIDAS compliant signatures with full audit trails
Setting Up Authentication
Secure authentication is the foundation of any production-ready eSignature integration. HelloSign provides multiple authentication methods suited to different use cases, from simple API key authentication for server-to-server integrations to OAuth 2.0 for applications where users connect their own accounts. Understanding these patterns and implementing them correctly protects your application and users from unauthorized access.
API Key Authentication
The simplest authentication method uses your API key directly in requests. Include the key in the Authorization header as a Basic Auth credential--the API key as username with an empty password. This approach works well for server-to-server integrations where you control the environment completely and don't need to connect user accounts. Store your API key in environment variables and never expose it in client-side code or version control.
OAuth 2.0 for Connected Accounts
OAuth 2.0 allows users to authorize your application without sharing their credentials. This flow begins by redirecting users to HelloSign's authorization URL, where they can grant your app specific permissions. After authorization, HelloSign redirects back with an authorization code that you exchange for an access token through a server-side request. Access tokens can be short-lived for better security or long-lived to reduce re-authorization friction for persistent integrations.
Token Management Best Practices
Store access tokens securely using encrypted session storage or a secure key-value store. Implement token refresh logic to handle expiration gracefully, and always have fallback authentication ready for cases where refresh fails. Rotate tokens periodically and immediately if you suspect any compromise. Never store tokens in local storage or client-side code where they could be accessed by malicious scripts.
1const response = await fetch('https://api.hellosign.com/v3/signature_request/send', {2 method: 'POST',3 headers: {4 'Authorization': `Basic ${Buffer.from(apiKey + ':').toString('base64')}`,5 'Content-Type': 'application/json'6 },7 body: JSON.stringify(requestData)8});Creating and Sending Signature Requests
The core of HelloSign integration is creating signature requests--the API endpoints that initiate document signing workflows. Whether you're sending contracts, agreements, or approval forms, understanding how to construct and send signature requests properly sets the foundation for your entire integration. The API accepts documents either as file uploads or file URLs, then manages the entire signing workflow with configurable options for multi-signer scenarios.
Basic Signature Request Implementation
Creating a signature request requires specifying the document title, subject line, message to signers, and recipient information. The signers array supports ordered signing, where documents cascade through signers in sequence. Set order values to control the flow--signer with order 0 receives the document first, then it proceeds to order 1, and so on. The signing_options object controls what methods signers can use to complete their signature, including drawing, typing, uploading, or phone-based signing.
Handling File Uploads
For applications where users upload documents directly, you'll need to handle multipart form data. HelloSign's endpoint accepts files as multipart/form-data with the file[] field for multiple documents. When building file upload flows, consider using Next.js API routes with appropriate body parsing configuration. Validate file types and sizes before sending to HelloSign to avoid unnecessary API calls and provide better user feedback on invalid uploads.
Using Templates for Recurring Documents
Templates save significant development time for documents used repeatedly. Create templates through the HelloSign web interface or API, defining signer roles and signature fields. When sending requests from templates, reference the template ID and provide signer information. Template fields can include text fields, checkboxes, and date fields that recipients fill during signing. Custom fields allow pre-populating data programmatically, reducing manual entry for signers and speeding up workflow completion.
1import { HelloSign } from 'hellosign-sdk';2 3const client = new HelloSign({ key: process.env.HELLOSIGN_API_KEY });4 5async function createSignatureRequest({ title, subject, message, signers, files }) {6 const options = {7 test_mode: process.env.HELLOSIGN_TEST_MODE === 'true' ? 1 : 0,8 title,9 subject,10 message,11 signers: signers.map((signer, index) => ({12 email_address: signer.email,13 name: signer.name,14 order: index15 })),16 file_urls: files,17 signing_options: {18 draw: true,19 type: true,20 upload: true,21 phone: false,22 default_type: 'draw'23 }24 };25 26 return await client.signatureRequest.send(options);27}Building Embedded Signing Experiences
Embedded signing provides a superior user experience by keeping visitors on your site throughout the document signing process. Unlike remote signing where users receive email links to HelloSign's domain, embedded signing presents the signing interface directly within your application. This maintains brand continuity, reduces abandonment, and keeps users engaged with your workflow without navigating away to external sites.
Understanding Embedded vs Remote Signing
Remote signing redirects users to HelloSign's domain via email links, which works well for simple use cases but can disrupt user attention and make tracking completion more difficult. Embedded signing requires additional setup--after creating a signature request, you must generate an embedded signing URL for each signer. This URL is then loaded in an iframe or webview within your application. The tradeoff is slightly more implementation complexity for significantly better user experience and higher completion rates.
Generating Embedded Signing URLs
To generate an embedded signing URL, call the sign_url endpoint with the signature request ID and signer information. The response includes a time-limited signing URL that can be embedded in your application. These URLs expire after a configured period, so generate them just before displaying them to users. Consider implementing a refresh mechanism for longer workflows to prevent URL expiration mid-process.
Implementing Embedded Signing in React/Next.js
For React-based applications, build a signing component that loads the embedded URL server-side for security, then displays it in an iframe. The component should handle loading states gracefully, show appropriate error messages if the signing URL fails to load, and communicate with your backend when signing completes. Consider adding event listeners to detect iframe navigation that might indicate signing completion or user departure.
Handling Signing Completion
After signers complete documents, HelloSign provides the signed files through the API. Configure webhooks to receive real-time notifications when signatures are obtained, then retrieve the completed documents automatically. Your application should update internal state to reflect the completed signature and trigger any downstream workflows like document storage, notification sending, or status updates in connected systems.
1'use client';2 3import { useState, useEffect } from 'react';4 5export default function EmbeddedSigner({ signatureId, signerEmail }) {6 const [signUrl, setSignUrl] = useState(null);7 const [loading, setLoading] = useState(true);8 9 useEffect(() => {10 async function fetchSignUrl() {11 const res = await fetch('/api/hellosign/sign-url', {12 method: 'POST',13 headers: { 'Content-Type': 'application/json' },14 body: JSON.stringify({ signatureId, signerEmail })15 });16 const data = await res.json();17 setSignUrl(data.signUrl);18 setLoading(false);19 }20 fetchSignUrl();21 }, [signatureId, signerEmail]);22 23 if (loading) return <div>Loading signing experience...</div>;24 if (!signUrl) return <div>Error loading signing URL</div>;25 26 return (27 <iframe28 src={signUrl}29 width="100%"30 height="800px"31 style={{ border: 'none', borderRadius: '8px' }}32 title="Document Signing"33 />34 );35}Implementing Webhooks for Real-Time Events
Webhooks enable your application to respond instantly to HelloSign events, making them essential for production integrations that need to track document status, trigger downstream workflows, or update connected systems. When a signer views, signs, or declines a document, HelloSign sends an HTTP POST to your configured endpoint. This real-time notification system keeps your application synchronized with document state without requiring constant polling of the API.
Webhook Setup and Configuration
Configure webhooks through the HelloSign dashboard or API. For production, use HTTPS endpoints with valid SSL certificates to ensure secure communication. Include a secret key in webhook configuration--HelloSign signs each request with this key, allowing you to verify request authenticity and prevent spoofed events from malicious actors. The x-hellosign-signature header contains the HMAC-SHA256 signature you verify against your secret.
Key Webhook Events to Handle
Several webhook events merit handling in most integrations. The signature_request_sent event fires when you create a new signature request--useful for logging, analytics, or triggering notification emails. Signature_request_viewed indicates when a signer first opens the document--track this for engagement metrics. Signature_request_signed confirms individual signature completion, enabling partial workflow progression in ordered signing scenarios. Signature_request_all_signed signals final completion, typically triggering document download and archive. Signature_request_canceled handles voluntarily canceled requests, important for cleanup operations.
Building Resilient Webhook Handlers
Webhook endpoints must be robust and idempotent because HelloSign may retry failed deliveries. Ensure your handler can process the same event multiple times without side effects by tracking processed event IDs and checking for duplicates before taking action. Validate webhook payloads for expected structure, reject requests with unexpected event types, and log all webhook deliveries for audit purposes while ensuring logs don't contain sensitive data. Implement proper error handling to return appropriate HTTP status codes that signal HelloSign whether to retry.
1import crypto from 'crypto';2 3export function verifyWebhookSignature(payload, signature, secret) {4 const computedSignature = crypto5 .createHmac('sha256', secret)6 .update(payload)7 .digest('hex');8 9 return crypto.timingSafeEqual(10 Buffer.from(signature),11 Buffer.from(computedSignature)12 );13}14 15export async function POST(request) {16 const payload = await request.text();17 const signature = request.headers.get('x-hellosign-signature');18 19 if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {20 return new Response('Invalid signature', { status: 401 });21 }22 23 const event = JSON.parse(payload);24 // Process event with idempotency check...25 return Response.json({ received: true });26}Performance Optimization Strategies
For applications sending numerous signature requests or handling high-volume document workflows, performance optimization becomes critical. Beyond basic implementation, consider caching strategies to reduce API calls, request queuing to handle rate limits gracefully, and CDN utilization for document delivery. These optimizations ensure your integration scales smoothly as transaction volume grows without introducing latency or reliability issues.
Caching for High-Volume Applications
Implement caching to reduce API calls for frequently accessed data. Template metadata changes infrequently and benefits significantly from caching with appropriate TTL values. Signature request status can be cached briefly, with invalidation triggered by webhook events. Use distributed cache systems like Redis for multi-instance deployments to ensure cache consistency across all application servers. Invalidating cache on webhook events keeps cached data synchronized with actual document state.
Request Batching and Rate Limiting
HelloSign implements rate limiting to protect service stability. While generous limits accommodate most applications, high-volume use cases benefit from request queuing and batch processing. Implement exponential backoff for 429 responses to handle rate limits gracefully without overwhelming the API. Consider implementing a request queue that throttles requests to stay within limits while maintaining throughput. For very high-volume scenarios, contact HelloSign to discuss rate limit increases tailored to your needs.
CDN and Edge Considerations
When embedding signing experiences or serving signed documents, CDN usage benefits document delivery and static assets. HelloSign's API responds with optimal performance from edge locations, but your application's document storage and delivery can benefit from CDN distribution. For Next.js applications, leverage Vercel's edge network for API routes that proxy HelloSign requests. Edge functions reduce latency by executing closer to users while maintaining server-side security for API credentials.
1async function makeRequestWithRetry(fn, maxRetries = 3) {2 for (let attempt = 0; attempt < maxRetries; attempt++) {3 try {4 return await fn();5 } catch (error) {6 if (error.status === 429 && attempt < maxRetries - 1) {7 const delay = Math.pow(2, attempt) * 1000;8 await new Promise(resolve => setTimeout(resolve, delay));9 continue;10 }11 throw error;12 }13 }14}Security Best Practices
Security is paramount for eSignature applications that handle legally binding documents and sensitive business agreements. Beyond basic authentication, implement comprehensive security measures including API key protection, HTTPS enforcement, input validation, and webhook security. These practices protect your application, your users, and the legal integrity of the documents being signed.
API Key Protection
API keys provide complete access to your HelloSign account, making their protection critical. Store keys exclusively in environment variables, never commit them to version control, and restrict access through your hosting platform's secret management. Rotate keys periodically, especially after team member departures or potential exposure. Consider implementing key rotation scripts that can update keys across multiple environments with minimal downtime. Monitor API usage for unusual patterns that might indicate a compromised key.
HTTPS Enforcement
All API communication must use HTTPS to prevent man-in-the-middle attacks. Next.js enables HTTPS by default in production deployments, but verify your hosting configuration ensures SSL certificates are properly configured and renewed. For local development and webhook testing, use tools like ngrok that provide HTTPS tunnels. Never allow fallback to HTTP, even for development environments, to catch mixed content issues early.
Input Validation and Sanitization
Validate all user inputs before sending to HelloSign. While the API handles most input safely, validation prevents abuse and provides better error messages to users. Check required fields, validate email formats, enforce length limits, and sanitize any user-provided content that appears in documents or messages. Implement server-side validation as the authoritative check, since client-side validation can be bypassed.
Webhook Security
Beyond signature verification, validate webhook payloads for expected structure and event types. Reject requests with unexpected data formats or event types. Log all webhook deliveries for audit purposes while ensuring logs exclude sensitive data like API keys or signing URL parameters. Implement idempotent handlers that can safely process duplicate deliveries from retry logic.
Next.js Integration Patterns
Next.js provides excellent patterns for integrating HelloSign's API into modern web applications. Server Actions handle form submissions with progressive enhancement, API routes proxy requests while protecting credentials, and TypeScript support improves development experience with type safety. These Next.js capabilities combine with HelloSign's API to create secure, performant eSignature workflows.
Server Actions for Form Submissions
Next.js 14+ Server Actions provide an elegant pattern for signature request creation. Keep form handling server-side while maintaining progressive enhancement--forms work even without JavaScript. Server Actions execute on the server where API credentials are secure, returning results directly to client components. This pattern simplifies your code by eliminating explicit API route handlers for simple signature request scenarios.
API Routes for Proxy Requests
Expose HelloSign functionality through Next.js API routes, providing a single endpoint for client-side applications while keeping credentials server-side. API routes handle authentication, request formatting, and error handling in one place. This centralized approach makes it easy to add authentication checks, rate limiting, or request validation that applies to all client requests.
TypeScript Type Definitions
Define TypeScript interfaces for HelloSign responses to improve development experience and catch errors early. Type definitions document expected response structures, enable autocomplete in your IDE, and provide compile-time checking for data access. Create interfaces for common types like SignatureRequest, Signature, and WebhookEvent to bring type safety throughout your integration code.
1'use server';2 3import { HelloSign } from 'hellosign-sdk';4 5const client = new HelloSign({ key: process.env.HELLOSIGN_API_KEY });6 7async function createSignatureRequest(formData: FormData) {8 'use server';9 10 const title = formData.get('title') as string;11 const signerEmail = formData.get('signerEmail') as string;12 const signerName = formData.get('signerName') as string;13 14 try {15 const signatureRequest = await client.signatureRequest.send({16 test_mode: 1,17 title,18 subject: `Signature requested: ${title}`,19 message: 'Please review and sign this document.',20 signers: [{21 email_address: signerEmail,22 name: signerName23 }],24 file_urls: ['https://example.com/document.pdf']25 });26 27 return { 28 success: true, 29 requestId: signatureRequest.signature_request.signature_request_id 30 };31 } catch (error) {32 return { success: false, error: error.message };33 }34}Real-World Integration Patterns
Successful HelloSign integrations demonstrate measurable business impact across industries. From contract management systems to sales workflows to HR onboarding, these real-world patterns show how eSignature APIs transform document-heavy processes. Companies like Flippa and Greenhouse have achieved significant efficiency gains by automating document workflows through HelloSign's API.
Contract Management Systems
For applications managing multiple contracts, implement a workflow that tracks document state across the entire lifecycle. Store HelloSign signature_request_id values in your database and use webhooks to update status. Create a state machine that progresses contracts from pending_signature to partially_signed to completed, with appropriate actions at each transition. This pattern keeps your internal systems synchronized with document status without manual updates.
Sales Agreement Automation
Companies like Flippa have achieved documented 80% increases in sales velocity through HelloSign integration. The pattern typically involves CRM-triggered signature requests, automatic follow-up reminders, and immediate document storage upon completion. Templates standardize agreement structure while custom fields inject deal-specific information automatically, reducing manual entry and accelerating time-to-close.
HR Onboarding Flows
Human resources applications benefit significantly from eSignature integration. Greenhouse's documented 30% improvement in onboarding efficiency demonstrates the impact of document automation. Automate offer letter distribution, NDA signing, and policy acknowledgment through templated workflows that trigger automatically when new hires are added to the system. Track completion status across all onboarding documents to ensure compliance before an employee's first day.
Testing Your Integration
Comprehensive testing ensures your HelloSign integration handles all scenarios reliably before deployment. The platform's test mode provides a sandbox environment where you can test complete workflows without generating legal signatures. Combine unit tests, integration tests, and end-to-end testing to validate every aspect of your implementation.
Unit Testing Strategies
Mock HelloSign API responses in unit tests to ensure deterministic behavior and fast execution. Create mock response factories that generate realistic API responses for different scenarios--successful requests, error conditions, edge cases. Test your integration logic independently of the actual API calls, verifying that your code handles responses correctly and transforms data as expected.
Integration Testing with Test Mode
Use test_mode for integration tests that exercise actual API calls. Test mode requests don't generate legal signatures but otherwise behave identically to production, including webhook delivery and response structure. Test complete workflows including document creation, signer actions, and completion handling. Clean up test requests after verification to keep your test account organized.
End-to-End Testing Considerations
For complete E2E testing, simulate the signing process programmatically where possible. The HelloSign test API allows creating test signatures without manual intervention for certain scenarios. Combine API-level testing with UI testing tools to validate embedded signing flows and user interactions. Include error scenarios in your E2E tests to verify error handling and user feedback.
1describe('Signature Request Creation', () => {2 it('creates signature request with correct parameters', async () => {3 const client = new HelloSign({ key: 'test-key' });4 5 jest.spyOn(client.signatureRequest, 'send')6 .mockResolvedValue({7 signature_request: {8 signature_request_id: 'test-request-id',9 title: 'Test Document',10 is_complete: false11 }12 });13 14 const result = await createSignatureRequest({15 title: 'Test Document',16 signers: [{ email: '[email protected]', name: 'Test User' }]17 });18 19 expect(result.signature_request_id).toBe('test-request-id');20 });21});Compliance and Legal Considerations
Electronic signature integrations must consider legal compliance to ensure signed documents hold up in court and meet regulatory requirements. HelloSign signatures comply with major electronic signature regulations, but your implementation must capture necessary consent and follow best practices for legal validity.
Electronic Signature Legality
HelloSign signatures comply with the ESIGN Act, UETA, and eIDAS regulations in the United States and European Union respectively. This means signatures hold the same legal weight as handwritten signatures for most document types. When building integrations, ensure your document workflows capture necessary consent with clear statements acknowledging electronic signature. Provide download or print options where required by regulation, and retain audit trails that document the signing process including timestamps, IP addresses, and signer actions.
Data Retention and Privacy
Handle document data according to privacy regulations applicable to your users. HelloSign provides options for deleting completed signature requests and associated documents. Implement data retention policies that align with your privacy commitments and regulatory requirements like GDPR. Consider how long you need to retain signed documents for legal or compliance purposes, and implement archival or deletion workflows accordingly.
Conclusion
Integrating HelloSign's eSignature API into modern web applications transforms manual document processes into automated workflows. The platform's emphasis on developer experience--comprehensive documentation, test mode for development, and well-designed APIs--makes implementation straightforward. Combined with Next.js's performance capabilities and modern React patterns, you can build signing experiences that are fast, secure, and seamlessly integrated into your application.
The patterns covered here--authentication, signature requests, embedded signing, webhooks, and performance optimization--provide a foundation for production-ready integrations. Whether you're building contract management systems, sales workflows, or HR onboarding tools, HelloSign's API delivers the functionality needed to digitize signature processes while maintaining legal compliance and user experience quality.
Start with test mode implementations, validate your workflows thoroughly, then deploy with confidence knowing your eSignature integration meets the standards of modern web development.
Key Takeaways
- Begin development with test_mode enabled to validate workflows without generating legal signatures
- Use embedded signing to keep users on your site throughout the workflow for better completion rates
- Implement webhooks for real-time event handling and automated workflow triggers
- Follow security best practices--rotate API keys regularly, validate all inputs, and verify webhook signatures
- Leverage Next.js Server Actions and API routes for clean, secure architecture
- Test comprehensively with unit tests, integration tests, and end-to-end validation before production deployment