Contents

• Prerequisites
• Subscribing to Notifications
• Request and Response Formats
• Actions
  • Send
  • partyComplete
  • complete
  • suspend
  • cancel
  • expire
  • partyOptedOut
  • partyNotificationFailed
• Notification Failure and Retries
• Notification Service Management
• Setting Up Your Server
• Authentication SIGNiX as an HTTP/HTTPS Client
• Implementation Process
• Unsuccessful Notification Testing Checklist
• Client Responsibilities for Continued Notifications
• Can't Use Push Notifications? Other Options
• References
  
  

Prerequisites

• All prerequisites for B2B API Integration
• Dev Resource familiar with Server setup and URL/web pages
• A URL that SIGNiX push notifications can be sent to with an active server page that uses software to process the request and generate a response
• Server that can respond to / acknowledge push notification in timely fashion
• Server that can communicate using TLS1.2 using updated cipher suites (as shown below)

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f)   ECDH x25519 (eq. 3072 bits RSA)

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030)   ECDH x25519 (eq. 3072 bits RSA)

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 (0x9e)   DH 2048 bits

TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 (0x9f)   DH 2048 bits

• Your server for receiving production push notifications must support HTTPS (http is only allowable in Signix’s Test environment). The server certificate must come from a widely trusted commercial certification authority. 

[

[Back to top]

Subscribing to Notifications

To subscribe or unsubscribe to events, contact your SIGNiX technical representative and provide a Base URL for receiving event notifications, as described below.

If there are certain Push Notifications that you would prefer to not receive, let your SIGNiX Rep know. SIGNiX can block any/all PNs from going out for the entire account. Note that this is not available on a per transaction basis.

If you have password requirements to meet, please discuss with your SIGNiX Representative.

If you will be using a new notification receiving server, you will also need to provide its public Static IP address so we can whitelist it in our firewall. You will want to use Port 80 for http and Port 443 for https (note that Production ONLY allows for https). Any variation from those common default Ports, please let us know right away to determine best course of action.

[Back to top]

Request and Response Formats

Your notification receiving server must offer a single-entry point for receiving notifications. SIGNiX PN requests will include your Base URL with appendage of: ? + action + the appropriate request parameters for the event.

Notification information is encoded into the following request parameters:

• action - The type of event that occurred. See below for valid values.

• id - Signix Document Set ID for the transaction in which the event occurred. Example: “id”:”1494353ca93: -7d01: -6f6de9aa:2x3f39”

• extid – Client Transaction ID for the transaction in which the event occurred. Let your SIGNiX Rep know if you cannot receive the Transaction ID as it can be turned off. Example: “extid”:”00012345”

• pid - The ordinal ID of the party that caused the event. Included only for events relating to a party. Format is Pnn. Example: “pid”: “P01”

• refid – The RefId of the party that caused the event. Included only for events relating to a party and where the <RefID> was included in the SubmitDocument for that party. Let SIGNiX Rep know if you cannot receive the RefID as it can be turned off. If you have both pid and refid, best practice is to digest refid and ignore pid. Example: “refid”: “Signer1”

• ts - The time the event occurred. Reported in "yyyy-MM-dd'T'HH:mm:ss" format default of Eastern time zone. Let your SIGNiX Rep know if you need a different time zone. Example: “ts”:”2014-10-24T15:44:19”

There is no message content in the requests. All the information supplied by the notification is in the URL.

!! IMPORTANT !!
When you have successfully received a push notification, return HTTP status code 200 OK. In addition to the 200 OK code, please include text of “OK” as content in the response. The response should have no content other than “OK”.

Any other status code will indicate some type of failure. There are no exceptions to this rule, and integrations will be rejected if this process is not followed.

[Back to top]

Actions

The following event types will be reported. Note that these are case-sensitive.

Send

Cause: Transaction was submitted / activated / started / resumed

Example: https://customer.com/landingpage?action=send&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

partyComplete

Cause: One specific Party has completed all their required actions.

Example: https://customer.com/landingpage?action=partyComplete&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

complete

Cause: Transaction completed, and all parties have completed all of their required tasks.

Example: https://customer.com/landingpage?action=complete&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

suspend

Cause: Transaction suspended because <SuspendOnStart> = yes, Signer failed authentication, or Submitter is modifying the Transaction.

Example: https://customer.com/landingpage?action=suspend&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

cancel

Cause: Transaction cancelled because Signer Opted Out & chose “Cancel” or Submitter cancelled it.

Example: https://customer.com/landingpage?action=cancel&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

expire

Cause: Transaction expired.

Example: https://customer.com/landingpage?action=expire&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

partyOptedOut

Cause: Party has opted out of the Transaction and chose a reason that cancels that Transaction.

Example: https://customer.com/landingpage?action=partyOptedOut&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

partyNotificationFailed

Cause: Party's email bounced.

Example: https://customer.com/landingpage?action=partyNotificationFailed&id=1495076a37d:-6cb8:-4f127ef3:2x3f39&extid=00012345&ts=2014-10-27T04:57:52

[Back to top]

Notification Failure & Retries

If SIGNiX fails to receive an “OK” response within a short timeout period, it will consider the request as failed. Failed requests are queued for re-sending. Every few minutes, SIGNiX will retry the request at the head of the resend queue. If it succeeds, the next queued request will be retried and so on. If there is another failure, retrying stops until the beginning of the next retry period. Please note that until we receive an “OK” response on the PN we retry, all of your other PNs going to same URL will be queued behind the first one. Until that PN succeeds, all of your PNs will essentially be blocked. This does not affect other Clients’ PNs as their PNs will be thrown in front of the failing PNs since they’ll be pointing to different URLs. We reserve the right to stop doing retries after 3 or more attempts.

[Back to top]

Notification Service Management

Push Notifications are designed to rapidly deliver small messages to inform your workflow. Please note and accommodate the following behaviors in your implementation. SIGNiX monitors for system misuse and reserves the right to suspend or terminate service if specified behaviors are not followed.

1. Respond to all push notifications within a few hundred milliseconds.

2. SIGNiX will make a good faith attempt to send push notifications as events occur in real time.

3. If the initial send attempt fails, SIGNiX will attempt to resend a notification 5 minutes later. Note that this delay may cause you to receive the notification out of order if another subscribed event occurs for that transaction before the resend.

4. SIGNiX may attempt to make more than one resend attempt at its discretion. Each attempt is at least 5 minutes after the previous attempt. Attempts may stop after the 3rd failed/rejected PN.

5. SIGNiX will timeout (fail) a send attempt after no less than 5 seconds and no more than 30 seconds (exact timing modifiable at SIGNiX’s discretion) if it does not receive the correct acknowledgement as described above from your server. SIGNiX expects a sent request to be immediately acknowledged, and we strongly recommend handling notification response asynchronously from other processing.

6. Occasional failures are somewhat common and are handled as in note 2 as we could be sending many thousands or millions of notifications per day. Substantive outages such as all notifications failing must be handled more critically. In these cases, SIGNiX may reasonably choose to temporarily disable notifications until your system has recovered its ability to receive. The client may request regeneration or resend and SIGNiX may be able to accommodate that request but we do not offer a response time guarantee and we may respond to these requests on a case by case, customized basis.

7. Since occasional failures are common, and are retried automatically, SIGNiX does not notify clients of occasional push failures. We will only notify you in the case of a substantial failure event, such as all or most of your pushes failing. Such outage notifications will occur through normal support communication channels.

8. SIGNiX will need to know the IP address or range of IP addresses for your notification receiving URLs so that they can be whitelisted in our firewall.

9. In the future, we may choose to include content in the notification message. SIGNiX recommends that you write your notification processing code so that content in the message does not cause regression issues.

10. Current push notifications focus on transactions. In the future, SIGNiX may make notifications available for additional events.

[Back to top]

Setting Up Your Server

You may implement your notification receiving server using any technology you choose, however, SIGNiX may only be able to help troubleshoot with a RESTEasy setup. Most of our users have had success using a receiving server, written in Java, for the JBoss Application Server with RESTEasy framework. Here are some items that might help you in getting setup.

You can read more about and see examples for how to use Resteasy: http://resteasy.jboss.org/

Access RESTEasy JAX-RS User Guide: http://docs.jboss.org/resteasy/docs/3.0.17.Final/userguide/html_single/index.html 

As you set up, few things to keep in mind:

✓ Push Notifications uses GET method

✓ In Webtest, SIGNiX accepts both HTTP (Port 80) and HTTPS (Port 443) Base URL

✓ In Production, SIGNiX only accepts HTTPS (Port 443) Base URL

✓ Static IP Addresses are currently required. If that is not possible, SIGNiX can clear your domain name instead.

✓ In Production and Webtest, SIGNiX is currently using TLS1.2

✓ URLs are case-sensitive and the PN entered at SIGNiX must match your URL exactly. When providing SIGNiX with the Base URL, make sure to check that it is an exact duplicate ✓ Your URL must have a landing page/active server page after the Domain as SIGNiX needs a target page when sending the URL. For example, Your URL: https://ABCCompany.hfc.comcastbusiness.com Then, include the landing/target page name such as “landingpage”, “landingpage.aspx”, “Index.jsp”, etc. Provide SIGNiX a full Base URL. Here are some examples:

https://ABCCompany.hfc.comcastbusiness.com/index.aspx

https://ABCCompany.hfc.comcastbusiness.com/PushNotifications

https://ABCCompany.hfc.comcastbusiness.com/PushNotifications/index.aspx

https://ABCCompany.hfc.comcastbusiness.com/PushNotifications.aspx

https://ABCCompany.hfc.comcastbusiness.com/PushNotifications.jsp

[Back to top]

Authenticating SIGNiX As An HTTP/HTTPS Client

SIGNiX may make outgoing calls to a customer site, for example to do push notifications or to retrieve documents
to be signed. Customers should require clients making such requests to authenticate before allowing access.

This document explains the types of client authentication that SIGNiX supports.

HTTP Client Authentication

SIGNiX supports HTTP Basic and Digest authentication in outgoing calls it makes to other sites. SIGNiX and the site operator must agree on a user ID and password to use to access the site.

SIGNiX does not currently support realms. All requests to the same host will get the same user ID and password, regardless of the Realm.

Server Setup

To use this type of authentication, the site SIGNiX is calling must have its server configured to require one of these
methods. The details of how to do this depend on the type of web server the site has. SIGNiX customers must
handle this part themselves.

✓ NOTE 1: HTTP Basic authentication sends passwords in the clear and is not secure. It is strongly recommended that the server require HTTPS connections if this type of client authentication is used.

✓ NOTE 2: HTTP Digest authentication sends a hash of the password and not the password itself, but uses MD5 to form the hash. MD5 is no longer considered to be very secure. This method is also vulnerable to man-in-the-middle attacks, since the client does not authenticate the server when this method is used on its own. It is therefore recommended that the server require HTTPS connections if this type of client authentication is used. HTTPS provides the missing server authentication and encrypts the weakly hashed password data.

Testing a New Remote Site

If a remote site has a secured URL that SIGNiX can send requests to without causing a problem, SIGNiX can manually send test requests to the server to check whether the server will accept them.

SSL Client Certificates

The SIGNiX system supports SSL client authentication when it makes SSL calls as a client to other servers that require client authentication.

SIGNiX has a client certificate from a widely trusted CA. Any remote site can configure their server to use this certificate to validate SIGNiX requests. 

In order to download our latest Certificates, please take the following steps:

• • Go to https://webtest.signix.biz for Test Site or https://www.signix.net for Production
  • Click on the padlock in the address bar
  • Click on "details" (different depending on browser)
  • Look for "view certificate" button
  • Click on "certification path" and then select root and/or intermediate cert(s)
  • Click "view certificate" and then find "copy to file"

SIGNiX can also accommodate clients who want to use their own specific client certificate. Such a certificate should be self-signed or chain to a root that is specific to the site, and supplied to SIGNiX directly.

Sending Test Requests to a Site

If a remote site has a URL that SIGNiX can send requests to without causing a problem, SIGNiX can manually send test requests to the server to check whether the server will accept them.

[Back to top]

Implementation Process

1. Code your push notification receiving server and set it up on a test platform. Provide the URL of the server to SIGNiX, and also provide the public IP addresses of the server or servers associated with these URLs. Make sure your firewall will allow incoming requests from the Internet from the SIGNiX test platform. The SIGNiX test platform is at IP address 52.34.103.46 (webtest.signix.biz).

2. Submit test transactions to the SIGNiX test platform, and check that you receive and properly manage each push notification. Let SIGNiX know of testing status and results.

3. SIGNiX will confirm that each push notification is accepted in under 1 second.

4. Once ALL push notifications have been successfully tested and your Integration has gone through our Go-Live Review process, you may deploy your software to your production platform. Provide SIGNiX with the production Base URLs and the IP addresses of the corresponding production servers. Make sure your firewall will allow incoming requests from the Internet from the SIGNiX production platform. The SIGNiX production platform is at IP address 50.56.20.60 (www.signix.net).

5. Submit a few test transactions to the SIGNiX production platform and check that the results match the results from the test system. Let SIGNiX know of testing status and results.

6. SIGNiX will confirm that each push notification is accepted in under 1 second.

In order to ensure that push notifications come from SIGNiX, it is recommended that receivers of push notifications filter incoming requests by origin IP address, or implement a supported type of client authentication on push notification requests, as described in "Authenticating SIGNiX as an HTTP/HTTPS Client".

[Back to top]

Unsuccessful Notification Testing Checklist

If you are not receiving push notifications from SIGNiX, please go down the checklist with your team and confirm you have all of the following confirmed before contacting your SIGNiX Rep. SIGNiX will then provide you with any errors spotted in your test transaction, when possible, and provide resolution suggestions when possible. Client and SIGNiX will work together to resolve any PN issue but Client is required to follow each suggestion and provide feedback in a timely fashion as well as provide the appropriate dev resources to help resolve when necessary.

✓ Your server is Live

✓ URL provided to SIGNiX matches actual URL

➢ No spelling errors

➢ No spaces and no additional or missing text/characters

➢ Capitalization is correct for each letter

✓ You provided SIGNiX all of the IP addresses associated with your server for Webtest/Production

✓ Your IP address is not dynamic (could have updated to an unknown address for SIGNiX)

✓ It is true that Client has had no Server or Domain Name updates/changes

✓ You cleared/whitelisted SIGNiX’s IP address for Webtest/Production

✓ You have at least 1 of SIGNiX’s cipher suites

✓ The URL leads to an active server page that can process SIGNiX notifications.

✓ Your server knows and can digest the full PN Request sent by SIGNiX – including any variation per event in the appended transaction info

✓ Your URL is set up for ASPX or HTML, but not both

✓ Your URL’s Header is set to application/JSON

✓ Your Server is configured to RESTful interface

✓ Your Server is configured to handle ‘GET’ requests

✓ It is true that you do not have an ‘Idle Time-Out’ set to 0 on your Server

✓ You are using Port 80 for ‘http’ or Port 443 for ‘https’

✓ It is true that you did not apply a Password/Permission without letting SIGNiX know

✓ Check that your SSL certs are set up correctly on your server (i.e. all intermediate certificates are present, etc.). Check your site via an SSL testing page such as: https://www.ssllabs.com/ssltest/index.html

✓ You have SIGNiX’s Root Cert in your Trust Store

➢ Go to https://webtest.signix.biz.

➢ Click on the padlock in the address bar

➢ Click on "details" (different depending on browser)

➢ Look for "view certificate" button

➢ Click on "certification path" and then select root and/or intermediate cert(s)

➢ Click "view certificate" and then find "copy to file"

✓ If all of the above have been answered ‘YES’, contact your SIGNiX Rep and be prepared to share the following:

➢ Your Server’s Root Certs

[Back to top]

Client Responsibilities for Continued Notifications

Let your SIGNiX Rep know if you plan on doing any of the following after successful push notification setup. Please note that SIGNiX will attempt to honor any request asap but advance notice is required in order to meet your timelines. We cannot guarantee a fast turn-around and your integration might be affected with push notifications not being received and your flow breaking because of it.

✓ Updates to SSL Server Certificates

✓ Receiving server IP address changes

[Back to top]

Can't Do Push Notifications? Other Options...

SIGNiX strongly suggests the use of push notifications in every use case due to their low overhead and real-time nature. However, SIGNiX also recognizes there may be some applications that cannot accommodate the push notification concept due to restrictions on resources or capabilities.

In this case, a QueryTransactionStatus API call may be utilized. However there are some important considerations and restrictions:

 QTS calls are pulls on the SIGNiX system for data in relation to the Transaction. It is meant as an option for Clients that cannot use Push Notifications (which provide real-time event statuses) but it is not meant to behave at the same level or schedule as Push Notifications.

 QTS calls should be done, at most, every 10 minutes but preferably on a longer schedule in order to avoid multiple calls to a Transaction in a short span (which then opens the possibility of the pull event happening at the same time as a Signer action). This means that Client/Submitter will see their downloaded docs 1 to 10 minutes after transaction completes dependent on when Signer signs and Call is made (or more, dependent on determined schedule).

 Client can code to run QTS on a schedule AND/OR make available a button to the Submitter/Platform where they can trigger their own QTS manually to see update.

 The current Status of the Transaction is located in the first section (“ControlAreaTitle”) of the <Response> followed by additional details of events. For Clients only needing the trigger point for their automatic DownloadDocument Req, focus will be on that “Transaction Completed” (as shown below):

 This call can either be an AJAX query or be wrapped in a B2B call (see SIGNiX Embedded- Wizard - #1 Application Guide 1.3 July 2014 and beginning with page 15 “Calling the SIGNiX Embedding API from a Server” and pay attention to “Sessionless API” references).

QueryTransactionStatus - Request

<?xml version="1.0" ?>

<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>

<Sponsor>EnterYourSpec</Sponsor>

<Client>EnterYourSpec</Client>

<UserId>EnterYourSpec</UserId>

<Pswd>demodemo</Pswd>

</CustInfo>

<Data>

<DocumentSetID>16e892d265a:-7b5a:89202f6:2sbe7x</DocumentSetID>

<Request>{'objectType':'QueryTransactionStatus'}</Request>

</Data>

</SubmitAjaxRq>

[Back to top]

QueryTransactionStatus - Response

<SubmitAjaxRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status>

<StatusCode>0</StatusCode>

<StatusDesc>success</StatusDesc>

</Status>

<Data>

<Response>{"admin":{"controlAreaTitle":"Running","controls":[{"action":"Transaction_Suspend","confirmationMessage":"While changing the transaction, users will not be allowed to access the transaction and sign. When you're done with your changes, just click the \"Resume Transaction\" button.","description":"Push To Suspend","objectType":"TransactionControlButton","status":"Active","title":"Suspend"},{"action":"Transaction_Cancel","confirmationMessage":"Do you want to Cancel this Transaction ?","description":"Push To Cancel","objectType":"TransactionControlButton","status":"Active","title":"Cancel"}],"objectType":"TransactionAdminStatusControlList"},"documentSetTable":{},"documentTable":{"PDF:177875fa901:-4978:-2d7b5fc4:2sbe7x":{"id":"PDF:177875fa901:-4978:-2d7b5fc4:2sbe7x","objectType":"DocumentStatus","refId":"SpreentestConsentForm","started":null,"status":"Action Required"},"PDF:177875fa901:-4977:-2d7b5fc4:2sbe7x":{"id":"PDF:177875fa901:-4977:-2d7b5fc4:2sbe7x","objectType":"DocumentStatus","refId":"SpreentestForm1","started":null,"status":"Action Required"},"PDF:177875fa901:-497b:-2d7b5fc4:2sbe7x":{"id":"PDF:177875fa901:-497b:-2d7b5fc4:2sbe7x","objectType":"DocumentStatus","refId":"SpreentestForm2","started":null,"status":"Action Required"}},"hasOptedOutDocuments":false,"objectType":"TransactionStatus","partyTable":{"P01":{"id":"P01","objectType":"PartyStatus","refId":"First Signer","registrationStatus":{"description":"The party has not yet been authenticated. Personal data is editable.","objectType":"RegistrationStatus","title":"Pending"},"started":null,"status":"Action Required","updateable":{"objectType":"Bool","value":true}},"P02":{"id":"P02","objectType":"PartyStatus","refId":"Second Signer","registrationStatus":{"description":"The party has not yet been authenticated. Personal data is editable.","objectType":"RegistrationStatus","title":"Pending"},"started":null,"status":"Action Required","updateable":{"objectType":"Bool","value":true}}},"status":"0 of 2","statusCode":null,"taskTable":{"T01":{"fileName":null,"id":"T01","objectType":"TaskStatus","refId":"SID1","status":"Action Required","timestamp":null},"T02":{"fileName":null,"id":"T02","objectType":"TaskStatus","refId":"SID2","status":"Option Available","timestamp":null},"T03":{"fileName":null,"id":"T03","objectType":"TaskStatus","refId":"SID1","status":"Action Required","timestamp":null},"T04":{"fileName":null,"id":"T04","objectType":"TaskStatus","refId":"SID2","status":"Option Available","timestamp":null},"T05":{"fileName":null,"id":"T05","objectType":"TaskStatus","refId":"SID1","status":"Action Required","timestamp":null},"T06":{"fileName":null,"id":"T06","objectType":"TaskStatus","refId":"SID2","status":"Action Required","timestamp":null},"T07":{"fileName":null,"id":"T07","objectType":"TaskStatus","refId":"SID3","status":"Action Required","timestamp":null}}}</Response>

</Data>

</SubmitAjaxRs>

TRANSACTION STATUS

Describes the status of the transaction and each document, party, and task in it. Filtered so that it only includes status for the transaction elements that the current user is allowed to know about.

Attributes

Constants

DOCUMENT STATUS

Describes the overall status of a document.

Attributes

Constants

PARTY STATUS

Describes the status of a party in a running transaction.

Attributes

Constants

TASK STATUS

Describes the status of a task.

Attributes

Constants

DOCUMENT SET STATUS

Describes the overall status of a document set / transaction.

Attributes

Constants

[Back to top]

References

✓ FlexAPI Documentation

✓ Push Notification Supporting Files

[Back to top]