Signing

In order to perform a digital signature on a document, a signature request needs to be created. A signature request defines the instructions for the signature engine — in its simplest form it specifies what is going to be signed and how it can be signed.

The request is sent to the DocumentService web service, the URL for which can be found here (look for WSDL): DocumentService

The typical life cycle of a document signature request is:

1. Upload the documents to be signed to the Session Data Storage (SDS)
2. Create a request with DocumentService
3. Redirect the user to Signicat for the signing request
4. Receive Status of the request
5. Download the signed document from SDS
   

Due to the modular design of Signicat Signature, it is possible to deviate somewhat from this list — but for the moment we’ll go through each of these steps in detail:

1. Upload documents to be signed to the Session Data Storage

The SDS is a REST based interface where documents are stored temporarily. While it is possible to send the documents within the SOAP call made to DocumentService, it is generally recommended to use SDS for transfer of documents because SDS’s REST based interface is more efficient and can deal with larger file sizes.

Instructions for using SDS can be found here: SDS (Session Data Storage)

2. Create a request with DocumentService

A SOAP request needs to be made to DocumentService to specify the instructions for the request. Put simply, this is where you describe what to be signed, who needs to sign it and how they should sign.

Requests are made up of five main components:

• Task(s)
• DocumentAction(s)
• Document(s)
• Subject(s)
• Notification(s)

More details about request creation can be found in the documentation: DocumentService v3

3. Redirect the user to Signicat for the signing request

When you want the user to start a signing action you will need to construct a URL leading the user back to signicat.

The URL will have the following format:

https://env.signicat.com/std/docaction/service?request_id=request_id&task_id=task_id&artifact=artifact

_{NOTE: all URL parameters must be properly URL encoded using UTF-8, as per RFC 3986.}

Example of a valid signing url: https://preprod.signicat.com/std/docaction/demo?request_id=10112015xwufkg8j94nfikhn0t26mvmme13mqzd37ok0tn5pv9am9y4hl&task_id=task0

For a code example of a simple request using C#, see the following: Creating a simple document order with one subject using Danish NemID

Request workflow and task order

The order in which the tasks of signature request is completed can be arranged by using “depends-on-task” within the Task datatype, allowing for complex workflows. For example: two customers and a salesman need to sign a contract, but the sales person may only sign when both of the customers have completed their signatures.

In this scenario the request would consist of three tasks (one for each signatory), so lets call them task A, B and C.

• first option is to let the two customers sign in parallel, this would be achieved by letting task C depend on task A and B
• alternatively all signatures could be sequential, this could be achieved by letting task B depend on A, and task C depend on B

Changing an existing request

There could be various reasons that you would want to change an existing request — the email address or mobile number of one of the signatories could have changed, the relevant signatories could change or the request could simply become obsolete.

• Existing requests can be deleted by using deleteRequest
• Notifications can be disabled and new notifications can be added to an existing request by using disableNotification and addNotification
• Tasks can be disabled and new ones added to existing requests by using disableTask and addTask

4 – Receive Status of the request

When the document order was created, you most likely defined a documentactionrequest in order for notifications and callbacks to notify your server (or other recipient) about actions being taken by the signer — whether it’s a request being created, cancelled or completed. We provide three complementary mechanisms for this:

1. Notification by redirect
2. Notification by server-to-server callback
3. Notification by messaging

All are optional and may be used independently.

Notification by redirect

When you’re creating a document order, the documentactionrequest allows you to specify three different URLs where Signicat can redirect the end user when they have signed (or declined to sign) a document. These cover the following scenarios:

The URLs are specified for each signing order, and may contain HTTP parameters with session specific or transaction specific values. The end user will not be redirected at all if on-task-complete is missing in the request when a document has been signed.

HTTP redirection cannot be guaranteed, however; the end user may close his browser before the redirect has completed or network problems may prevent the HTTP request to reach your server.

Notification by server-to-server callback

The documentactionrequest allows you to specify a URL on your server that Signicat should call when a signing order is created or completed. Signicat’s server will make an HTTPS call to this URL directly (or HTTP, but insecure HTTP calls are only supported in preprod). This is a server-to-server call, not involving the end user’s browser at all. You may specify a static URL that should be used for all signing orders, or you may specify a different URL for each order. The URL may contain any number of parameters such as session specific parameters or user specific information. You may also add parameters for added security, such as a static or dynamic password. Signicat will always add the requestId in an extra HTTP parameter.

The HTTP call will be made by Signicat’s server and will come from a fixed IP address. In order for these to work, Signicat must be informed about the destination address on your end, as our firewall blocks notifications to unknown URL’s by default.

The notification is specified in the request with these values:

You may specify more than one notification if you want Signicat to make more than one callback. Delivery of the notification is guaranteed as long as your server is able to receive HTTP calls.

When doing server-to-server notification, you may choose to add additional security features to make the notification reliable. An example would be to:

1. Create a one time token (a random number or string) for each request.
2. Add the token to the callback url in a http parameter called i.e. “secure”.
3. When Signicat makes the callback, validate that the value of the parameter is correct.

This would protect against fake HTTP callbacks since senders of fake callbacks would not be able to guess the correct parameter value.

Notification by messaging

The documentactionrequest allows you to specify a (mobile) phone number or an email address where Signicat should send a message when a document order is created or completed — you may specify one or more notifications like this. Typical uses of this is to send a message to a back office address, send a message to the end user or even send a message to a local workflow system. Each message is specified in each request, and the text can be personalized or contain user specific information like customer number, transaction details and so forth. Delivery of the notification depends on the SMS and email infrastructure and cannot be guaranteed.

The notification is specified in the documentactionrequest with these values:

An example can be found here: Notify and get notified when a document order status changes

Notes about security

You should not depend on the correctness of the information you get in the notifications. The notification should be regarded as a “hint” about a possible status change in the signing order. You must always call getStatus on Signicat’s web service after you have received a notification to get reliable, updated status information.

The “Notification by server-to-server callback” can be extended to include security mechanisms that would make the notification reliable. However, Signicat still recommends that you always call getStatus to get reliable information. The information you get in return from the getStatus web service call will always be correct and reliable.

Other web service calls

It is possible to get information about existing requests by using getStatus and getRequestHistory which, in combination, yields a precise picture of any given request’s as well as related status events.

An example of this can be found here: Check the status and result of a document order

_{NOTE: getStatus can be used for checking status on selected request, but in general, polling should be avoided. Instead, notifications and callbacks should be used.}

5 – Download the signed document from SDS/Signicat Archive

In order to do this, you should know about the different formats the signed document may take. This is described in greater detail in the next section: The Signature Result.