TL;DR: Full-stack embedded signing puts the signing page inside your own app, so users never leave it. Your backend sends the document and asks for a signing link. Your frontend shows that link in an iframe, and a webhook reports when signing is done. Our embedded signing page shows what the signer sees.
A user logs in to finish a task, such as signing a lease or an onboarding form. In many apps, the last step sends them away. They get an email, follow a link to another site, sign, and then try to find their way back.
Each of those hops is a chance to lose the user. This guide shows how to keep the whole flow in your app, from the server code to the browser.
What is full-stack embedded signing?
Full-stack embedded signing means your backend and frontend work together to show a signing page inside your app. The user signs without an email link or a trip to another website.
Think of paying at a shop counter. A card reader on the counter lets you pay on the spot. Being sent to the bank to pay would work too, but most people would walk out.
Our guide to embedded signing vs redirect signing compares the two approaches. For the product side of in-app signing, read our post on embedded signing for in-app contract signing. This post stays with the code.
What will you build in this guide?
You will build an app in ASP.NET Core, the .NET (Microsoft’s developer platform) web framework named after Active Server Pages (ASP). The app uses the Model-View-Controller (MVC) pattern.
- Send a document for signing from your backend.
- Turn off our emails so signing stays in your app.
- Create a signing link on the server.
- Show the signing page in an iframe.
- Check each webhook’s signature and act on the finished document.
What do you need before you start?
Have these ready before you write any code.
- A free API sandbox account for testing.
- An API key from your developer settings, kept in server configuration only.
- .NET 6 or later on your computer.
- Our .NET software development kit (SDK), installed in the steps below.
- A public webhook URL that our servers can reach.
Use ngrok or a similar tunnel to expose your local server while you develop. Run ngrok http 5000, then add the secure URL it gives you in the webhook settings.
How does the embedded signing flow work end to end?
We will use a made-up property app called RentEase. A property manager uploads a lease, and a tenant logs in to review and sign it.
The tenant never leaves RentEase. The same pattern fits HR onboarding, loan forms, software subscription terms and patient consent forms.
Sending the lease
- The property manager uploads the lease and enters the tenant’s details.
- Your backend sends the document to us with
DisableEmails = true. - We return a unique
DocumentId, which you save. - Your backend asks for an embedded signing link for the tenant.
Signing and finishing
- Your frontend loads the signing page in an iframe.
- The tenant signs inside RentEase.
- We send the Completed webhook event to your backend.
- Your backend updates the lease status and shows a confirmation.
How do you set up the ASP.NET Core project?
Create a new MVC project and add our SDK package.
dotnet new mvc -n RentEase
cd RentEase
dotnet add package BoldSign.Api
Add your API key to appsettings.json. That file uses JavaScript Object Notation (JSON).
{
"BoldSign": {
"ApiKey": "YOUR_BOLDSIGN_API_KEY",
"BaseUrl": "https://api.boldsign.com"
}
}
Create the API client in your service setup.
var apiClient = new ApiClient(
Configuration["BoldSign:BaseUrl"],
Configuration["BoldSign:ApiKey"]
);
How do you send the document from your backend?
Your backend sends the lease to the BoldSign API when the manager uploads it. The setting that matters most is DisableEmails = true, which stops us from emailing the signer a link.
var documentClient = new DocumentClient(apiClient);
List<FormField> formField = new List<FormField>
{
new FormField(
id: "Signature",
type: FieldType.Signature,
pageNumber: 1,
bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30))
};
var documentDetails = new SendForSign
{
Title = "Lease Agreement - RentEase",
DisableEmails = true,
Signers = new List<DocumentSigner>
{
new DocumentSigner(
signerName: "Tenant Name",
signerType: SignerType.Signer,
signerEmail: "tenant@example.com",
formFields: formField)
},
Files = new List<IDocumentFile>
{
new DocumentFilePath
{
ContentType = "application/pdf",
FilePath = "lease.pdf"
}
}
};
var documentCreated = documentClient.SendDocument(documentDetails);
var documentId = documentCreated.DocumentId;
Save the document ID in your database right away. Every later step needs it, including matching webhook events to the right lease.
Why must emails be turned off?
With emails on, we send the tenant a separate signing link. The tenant might sign from that email and skip your app. Setting DisableEmails = true keeps the iframe as the one way in.
How do you generate the embedded signing link?
Ask for the link on the server, just before the tenant opens the signing page. The embedded signing link is tied to one signer and one document.
var documentClient = new DocumentClient(apiClient);
var embeddedSigningLink = documentClient.GetEmbeddedSignLink(
documentId: "YOUR_DOCUMENT_ID",
signerEmail: "tenant@example.com"
);
var signLink = embeddedSigningLink.SignLink;
// Return signLink to the frontend, never the API key
Pass only the URL to your view and keep the API key on the server. You can set how long the link works with the signLinkValidTill setting.
How do you show the signing page in an iframe?
Put the signLink in an iframe in your Razor view. The controller action first checks that the logged-in tenant owns the document.
<iframe
src="@Model.SignLink"
width="100%"
height="700"
title="Sign your lease agreement">
</iframe>
// Controller action that returns the signing view
public IActionResult SignDocument(string documentId)
{
var tenantEmail =
User.FindFirst(System.Security.Claims.ClaimTypes.Email)?.Value;
// Verify this document belongs to the authenticated tenant
var record = _documentService.GetDocument(documentId, tenantEmail);
if (record == null) return NotFound();
var signLink = _documentService.GetSignLink(documentId, tenantEmail);
return View(new SignDocumentViewModel
{
DocumentId = documentId,
SignLink = signLink
});
}
Once the view loads, the tenant reads and signs the lease without leaving RentEase. You can also set a redirectUrl to send the tenant to a confirmation page after signing.
Which webhook events should you handle?
After the tenant signs, we send a Hypertext Transfer Protocol (HTTP) request to your webhook endpoint. Three webhook events matter most in this flow.
| Event | When it fires | What to do |
|---|---|---|
| Signed | A recipient signs the document | Update that signer’s status |
| Completed | All recipients have signed | Download the signed PDF and tell the manager |
| Declined | A recipient declines to sign | Alert the property manager |
Use Completed as the trigger for final actions. Download the signed PDF there, unlock the next step and send any confirmation. Our guide to downloading documents with webhook callbacks shows that step in detail.
How do you verify the webhook signature?
Every webhook we send carries a signature made with a hash-based message authentication code (HMAC) and Secure Hash Algorithm (SHA) 256. Check it before you trust the event.
x-boldsign-signature: t=1668693823, s0=9b7adf82fbd470cce0cdb8106d7cb023e547999ada5e8c9ad02306cd22ee7ca9
The signed text is the timestamp, a dot and the raw request body. Our guide to verifying webhook events explains each part. The SDK’s WebhookUtility.ValidateSignature method does the check and rejects events older than 5 minutes by default.
What does the webhook handler look like?
The handler below answers our verification ping, checks the signature and then hands the event to a background task.
[HttpPost("webhooks/boldsign")]
public async Task <IActionResult> BoldSignWebhook()
{
using var reader = new StreamReader(Request.Body);
var json = await reader.ReadToEndAsync();
// Respond to BoldSign's verification ping immediately
if (Request.Headers["X-BoldSign-Event"] == "Verification")
return Ok();
var signature = Request.Headers["X-BoldSign-Signature"].ToString();
var secretKey = _configuration["BoldSign:WebhookSecret"];
// Verify HMAC before any processing
try
{
WebhookUtility.ValidateSignature(json, signature, secretKey);
}
catch (BoldSignSignatureException)
{
return Forbid();
}
// Acknowledge immediately, then process async
var evt =JsonSerializer.Deserialize<BoldSignEvent>(json);
_ = Task.Run(() => ProcessEvent(evt));
return Ok();
}
void ProcessEvent(BoldSignEvent evt)
{
if (evt.Event.EventType == "Completed")
{
var documentId = evt.Data.DocumentId;
var messageTitle = evt.Data.MessageTitle;
var document = _documentService.MarkCompleted(documentId);
var documentClient = new DocumentClient(apiClient);
// Download final signed document
using (var stream = documentClient.DownloadDocument(documentId))
{
Directory.CreateDirectory("SignedDocuments");
// Add your document title here
var documentTitle = "Your Document Title";
var filePath = Path.Combine("SignedDocuments", $"{documentTitle}.pdf");
using (var fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write))
{
stream.CopyTo(fileStream);
}
}
_notificationService.NotifyManager(document.TenantId, document);
}
}
Note: In production, use a background worker or a queue in place of
Task.Run. A queue keeps the event safe if your app restarts.
Return a 200 status code quickly, then do the slow work. Your endpoint must answer within 10 seconds, or we count the delivery as failed and retry it.
Why does the handler need the raw request body?
The signature covers the body exactly as we sent it. Parsing or reformatting the body first changes it, and the check fails.
ASP.NET Core lets you read the request body stream once by default. Call EnableBuffering() or use middleware when you need to read it again after the check.
What security practices should you follow?
Most of the work is keeping secrets on the server and checking who is asking.
Protect links and keys
- Create signing links only on the server, and keep the API key out of browser code.
- Check that the logged-in user owns the document before you create a link.
- Create links just before use, with a short
signLinkValidTilltime. - Serve your app and webhook endpoint over Hypertext Transfer Protocol Secure (HTTPS).
Protect your webhook endpoint
- Verify the signature on every event before you act on it.
- Compare signatures in constant time, which blocks timing attacks.
- Store processed event IDs and skip repeats, since retries can send an event twice.
Your app owns user identity, access control and the user experience. We handle the signing session and keep a record of each signature in the document’s audit trail.
Which use cases suit embedded signing?
Embedded signing fits any flow where signing is one step in a longer task inside your app. Here are common examples.
HR, education and software sign-ups
New hires can sign employment contracts, non-disclosure agreements and policy forms in the HR portal. Students can sign enrollment terms and codes of conduct inside a learning platform. Software buyers can accept subscription terms as part of an in-app upgrade.
Loans, insurance and healthcare
Banks and lenders can collect loan agreements and disclosures at the end of an online application. Insurers can have customers sign policy papers during purchase, so cover can start right away. Clinics can collect consent forms in a patient portal before the visit.
In each case, your app can unlock the next step once the Completed event arrives.
Which BoldSign plan do you need for embedded signing?
Live embedded signing, webhooks and production API access come with the Enterprise API plan. It starts at $30 a month with 40 envelopes, and each extra envelope costs $0.75, as listed on our pricing page in November 2026.
Prices are in USD. You can build and test everything in this guide first with a free API sandbox account.
How do you start building your embedded signing flow?
A good way to learn is to run the sample against the sandbox and sign a test lease yourself.
- Create a free API sandbox account and send your first embedded document.
- Read our API getting started guide for every endpoint and SDK.
- Book a demo to talk through your setup, or ask our support team.
Frequently asked questions
How do I get an embedded signing link from BoldSign?
Call GetEmbeddedSignLink from your server with the document ID and the signer's email address. The response holds a signLink URL that you load in an iframe. Keep this call on the server so your API key stays private.
How do I authenticate BoldSign API requests?
Do signers need a BoldSign account to sign in my app?
No. Signers open the embedded link and sign without creating an account or paying anything. Your app decides who may open the signing page.
How does my app know when a document is fully signed?
Listen for the Completed webhook event. It fires when every recipient has signed, so you can download the final PDF and move the user to the next step.
Can I put my own logo and colors on the embedded signing page?
Yes. Set up a brand with your logo and colors, and the signing page shows it. Brand settings can also hide the decline and reassign buttons.
What happens if my webhook endpoint is down?
We retry the delivery six times with growing gaps, over about 24 hours. Store each event ID you process and skip any repeat, so a retried event does no harm.
Can I test embedded signing for free?
Yes. A free API sandbox account lets you send test documents, open embedded signing links and receive webhooks before you pay for live use.
Is a document signed in an iframe legally binding?
Yes, when the signing meets the usual electronic signature rules: the signer agrees to sign electronically and a record of the signing is kept. The iframe changes where the page shows, not how the signature is captured. Check the rules for your document type and country.