DocuSign Integration: API, Embedded Signing & Webhook Setup

Integrating DocuSign integration with a web application for electronic signature on website often encounters OAuth errors, incorrect anchor strings, or misconfigured webhooks. Typical issues include misconfigured redirect URIs, outdated SDK versions, and mismatched PDF tags. All this leads to runtime failures and lost deals. We specialize in such DocuSign API integration: we have completed over 30 projects where DocuSign is used for signing contracts, acts, and invoices. On average, our clients reduce document processing time by 40% and accelerate deal closure by 3 times. Embedded signing via DocuSign API improves completion rate by 3x compared to email signing, saving up to $1,500 per month in manual processing costs.

Why Choose DocuSign?

DocuSign is the market leader in electronic signatures in the US and Europe. It supports legally binding signatures under eIDAS (Europe), UETA/ESIGN (USA), and several national standards. For the Russian market: DocuSign provides a simple electronic signature (SES) that is recognized in court if there is an agreement between the parties—this is sufficient for most commercial contracts. For more details, see the Official DocuSign documentation.

How Integration Works?

Typical flow:

1. User fills in data on the website → clicks "Sign contract"
2. Backend creates an Envelope in DocuSign with the document and recipients
3. User is redirected to DocuSign to sign (or receives an email)
4. After signing, DocuSign notifies the site via webhook
5. Backend downloads the signed document and saves it

We implement two scenarios: email sending or embedded signing—signing directly on the site. Comparison:

Application Setup

In DocuSign Developer Portal: create Integration Key → add redirect URI → request Secret Key. For testing—free Demo environment (account-d.docusign.com).

composer require docusign/esign-client 

OAuth: Obtaining a Token

DocuSign uses OAuth 2.0 Authorization Code Grant:

class DocuSignAuthService { public function getAuthUrl(): string { $params = http_build_query([ 'response_type' => 'code', 'scope' => 'signature', 'client_id' => config('docusign.integrator_key'), 'redirect_uri' => config('docusign.redirect_uri'), ]); return 'https://account-d.docusign.com/oauth/auth?' . $params; } public function handleCallback(string $code): string { $response = Http::withBasicAuth( config('docusign.integrator_key'), config('docusign.client_secret') )->asForm()->post('https://account-d.docusign.com/oauth/token', [ 'grant_type' => 'authorization_code', 'code' => $code, 'redirect_uri' => config('docusign.redirect_uri'), ]); return $response->json('access_token'); } } 

For server-side scenarios without user interaction—JWT Grant (service account).

Creating an Envelope and Sending for Signature

class DocuSignEnvelopeService { public function createEnvelope( string $accessToken, string $pdfPath, array $signers ): string { $config = new \DocuSign\eSign\Configuration(); $config->setHost(config('docusign.base_url')); $config->addDefaultHeader('Authorization', "Bearer {$accessToken}"); $apiClient = new \DocuSign\eSign\client\ApiClient($config); $envelopesApi = new \DocuSign\eSign\Api\EnvelopesApi($apiClient); $document = new \DocuSign\eSign\Model\Document([ 'document_base64' => base64_encode(file_get_contents($pdfPath)), 'name' => 'Contract', 'file_extension' => 'pdf', 'document_id' => '1', ]); $signHere = new \DocuSign\eSign\Model\SignHere([ 'anchor_string' => '/sig1/', 'anchor_x_offset' => '20', 'anchor_y_offset' => '-10', 'anchor_units' => 'pixels', ]); $recipientList = []; foreach ($signers as $i => $signer) { $tabs = new \DocuSign\eSign\Model\Tabs(['sign_here_tabs' => [$signHere]]); $recipientList[] = new \DocuSign\eSign\Model\Signer([ 'email' => $signer['email'], 'name' => $signer['name'], 'recipient_id' => (string)($i + 1), 'routing_order'=> (string)($i + 1), 'tabs' => $tabs, ]); } $envelopeDefinition = new \DocuSign\eSign\Model\EnvelopeDefinition([ 'email_subject' => 'Please sign the document', 'documents' => [$document], 'recipients' => new \DocuSign\eSign\Model\Recipients([ 'signers' => $recipientList, ]), 'status' => 'sent', ]); $result = $envelopesApi->createEnvelope( config('docusign.account_id'), $envelopeDefinition ); return $result->getEnvelopeId(); } } 

Embedded Signing: Signature Directly on the Site

Instead of redirecting to DocuSign—embedded iframe or redirect back to site:

public function getSigningUrl(string $accessToken, string $envelopeId, array $signer): string { $config = new \DocuSign\eSign\Configuration(); $config->setHost(config('docusign.base_url')); $config->addDefaultHeader('Authorization', "Bearer {$accessToken}"); $apiClient = new \DocuSign\eSign\client\ApiClient($config); $envelopesApi = new \DocuSign\eSign\Api\EnvelopesApi($apiClient); $viewRequest = new \DocuSign\eSign\Model\RecipientViewRequest([ 'authentication_method' => 'none', 'client_user_id' => $signer['id'], 'recipient_id' => '1', 'return_url' => route('contracts.signed'), 'user_name' => $signer['name'], 'email' => $signer['email'], ]); $result = $envelopesApi->createRecipientView( config('docusign.account_id'), $envelopeId, $viewRequest ); return $result->getUrl(); } 

Webhook: Notification of Signing

After signing, DocuSign sends XML with the new status. The server must process the request, verify that the status is Completed, and start downloading the document. We set up an endpoint that accepts POST requests and ensure it is accessible from the outside world. In production, HTTPS is mandatory.