OneSpan Sign Developer: Handover URL

Imagine you are developing an integrated application with OneSpan Sign. After the signer has completed signing, you want to find a way to synchronize the signing status change and take control of the e-signature process. There are a few technologies that you may already be familiar with, such as setting up a callback listener or utilizing the Javascript notifier. 

Handover URL, on the other hand, can also be used as a web hook and send your application with real time information when the signer has completed signing. In this blog, we will dive into the details of the Handover URL and share some tips on how to leverage this feature in your own integration. Let’s get started!

What is a Handover URL?

A Handover URL is a redirect link pre-set in the package settings, which allows you to determine where the signing ceremony will be relocated after a recipient interacts with a transaction. The URL will be triggered differently in certain ways. The most common scenario is when a signer has completed signing, the Handover URL will be displayed as an exit button both available at the global actions bar and the tool bar.
 
Other cases like when a recipient declines to sign a transaction, the Handover URL will be automatically triggered. 

Set Up Handover URL

There are three values you need to specify regarding to the Handover URL:

•    Handover Link Href: Defines the redirect URL
•    Handover Link Text: The text that will appear on the handover button
•    Handover Link Tooltip: The text that will appear when hovering over the handover button

Knowing the Handover URL is a package setting, it’s possible to set the default values in your account level. If your workflow simply requires to redirect the signing ceremony to a general completion page or your organization’s website, you can raise a request and send these three attributes to our support team then all the newly created packages will inherit the values.

Additionally, if you want to specify different endpoints or parameters for each package, setting the Handover URL at package level is a more flexible way to tackle it. 

REST API:

The attributes are hosted at “settings” > “ceremony” > “handOver”. See below: 

{
  "status": "DRAFT",
  "settings": {
    "ceremony": {
      "handOver": {
        "title": "You will be redirected to Google homepage",
        "href": "http://www.google.com",
        "text": "Exit to site"
      }
    }
  },
  "type": "PACKAGE",
  "name": "Customizing Signing Ceremony"
}

From here, the “title” attribute refers to the tooltip of the text.

Java SDK:

The equivalent code in Java SDK looks like:

.withSettings(DocumentPackageSettingsBuilder.newDocumentPackageSettings()
			.withHandOverLinkHref("http://www.google.com")
			.withHandOverLinkText("Exit to site")
			.withHandOverLinkTooltip("You will redirected to Google homepage")
		)				

.NET SDK:

.WithSettings(DocumentPackageSettingsBuilder.NewDocumentPackageSettings()
                        .WithHandOverLinkHref("http://www.google.com")
                        .WithHandOverLinkText("Exit to site")
 	       .WithHandOverLinkTooltip("You will redirected to Google homepage")
 	)

For Further Reading

Handover URL only notifies users of the signer completion event. If you are interested in more notification options, use the callback event notification listener. You can find more information about this feature in a the previous blog series and our feature guide:

Callback Event Notification – Part 1
Callback Event Notification – Part 2
Create a Callback Event Notification Listener Guide

Furthermore, if you are embedding the Signing Ceremony into an iFrame, there’s another mechanism to control the signing process through the Javascript notifier. It’s a solution with pure Javascript code, very light-weight to implement and test through the output. Check the feature guide for sample codes and more details:

JavaScript Event Notifier Guide

If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today