Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

HelloSign Embedded v2

"HelloSign Embedded v2" header image

For a little over a year, we at HelloSign have been building and testing a brand new version of our HelloSign Embedded library. Built from the ground up, this new version is designed to be much more robust and developer friendly with modern web standards and APIs in mind.

What is HelloSign Embedded?

Before we get into how V2 improves on the old version, it's first important to understand what exactly HelloSign Embedded is.

HelloSign Embedded is not what is seen inside of the modal when you or one of your users is signing or editing a signature request. Marking up documents, inserting signatures, or entering data into text fields are all done in an embedded iFrame which points to It’s a common misconception that the code that makes it all work lives in HelloSign Embedded, but in reality it’s all hosted on the HelloSign webapp at

HelloSign Embedded is simply a set of tools which allows you, as a developer, to embed signature requests created using the HelloSign API within your own website. It is only responsible for opening the signature request on within an iFrame, resizing and positioning the modal, as well as interpreting, delegating, and responding to messages sent by the HelloSign webapp.

With the exception of the close button and the modal container, HelloSign Embedded's footprint is invisible. It is merely a wrapper around the HelloSign webapp which allows embedding HelloSign signature requests within your own website quick and easy.

What's changed?

More intuitive and predictable APIs

HelloSign Embedded v2 follows a more standard API that developers would expect from a library like this. For example, if you wanted to hook into the underlying events (like “signed”) sent between HelloSign Embedded and the HelloSign webapp in older versions of HelloSign Embedded, you would need to pass a callback into the options object when calling, and then check that the event you received is the one you want.

// Old{
  messageListener(evtData) {
    if (eventData.event === HelloSign.EVENT_SIGNED) {

This was a bit clunky. Now, with the new version of HelloSign Embedded you instead simply bind an event listener of the desired type to the client instance.

// New

client.on('sign', () => {

No longer a singleton

HelloSign Embedded has historically been a singleton—only one instance could exist on the page at any given time.

// Old

function launchEmbedded(url) {{

Thinking forward to the future, we decided that the new version of HelloSign Embedded would benefit from being a class, which gives developers greater flexibility. For example, it can pave the way for opening multiple HelloSign Embedded frames at the same time, and it also allows developers to define common HelloSign Embedded configuration (like locale) at instantiation instead of every time the open() method is called. Although this is probably the biggest change between v1 and v2, we think it’s a step in the right direction.

// New

const client = new HelloSign();

function launchEmbedded(url) {;

If it helps, we've created a few projects to help you get started with HelloSign Embedded v2. You can find them here.

Better version control management

For older versions of HelloSign Embedded, we had always recommended importing it via a file on our CDN which would always be updated to include new features and fixes, called embedded.latest.js. This was done in an attempt to ensure that our customers always had the latest and greatest version of the library. However we found that an unintentional side effect of our good intentions meant that even updating a small piece of the library could incidentally break some customers’ implementations, which made it very difficult to add new features, fix bugs, and allow HelloSign Embedded to mature over time.

So with the new version of HelloSign Embedded, we've changed how the CDN works. We still offer a CDN version of our library—available through our official CDN—but we will no longer offer a similar “latest” version. Instead our users can import a specific version of HelloSign Embedded by simply entering the version name as part of the resource path. You can see an example of this below, where we’re importing version v2.6.0.

<script src=""></script>

To update the version of HelloSign Embedded, just change the version number. After every release, we publish our latest CDN links on our GitHub wiki here.

Improved debugging

HelloSign Embedded v2 now has an improved debugging system via debug. These debug messages are very comprehensive and cover most actions that HelloSign Embedded takes, allowing you to easily troubleshoot and diagnose issues. However, the debugger messages are not enabled by default. To enable HelloSign Embedded debugging for your current domain, you'll need to update your local storage. To do this, open up your browser's developer console, enter the following, then hit return:

localStorage.debug = 'hellosign-embedded:*';

Refresh the page, and now HelloSign Embedded will write debug messages to the developer console. For a complete signature request flow, it should look something like this:

A screenshot of HelloSign Embedded debug messages in the developer console

From now on (until you clear your website data) any HelloSign Embedded instance that lives on this domain will send debug messages to your web console. If you want to debug HelloSign Embedded on a new domain—say if you were testing on localhost originally but now want to debug on production—you’ll need to enter that command into your console again.

Try it now

If you’d like to try HelloSign Embedded, feel free to check out our starter projects to get you up and running. The HelloSign Embedded wiki is also a valuable resource, take a look at our quickstart guide which will help you create your first signature request and embed it in your web app.

If you already have a pre-existing implementation of HelloSign Embedded v1, don’t worry, upgrading to Embedded v2 should be relatively straightforward. For most simple implementations, it should only take a few minutes. Check out our v1 to v2 migration guide for more information, or reach out to our API Support team at, where one of our API Support Engineers will be happy to help you.

And if you find a problem, please reach out to us or open an issue on the HelloSign Embedded GitHub repository. Your contributions and feedback are essential in helping us build better tools for for you and your users.

Get news, insights and posts directly in your inbox

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form
Oops! Something went wrong while submitting the form.