AlphaTrust e-Sign

Appearance

On this page

Document Event Subscriptions ​

There are two methods that are supported for notifying your application of these status change events: (1) HTTP POST, and (2) HTTP GET.

TIP

If using HTTP POST, data elements are sent via a standard HTTP(S) POST of urlencoded name value pairs as an “application/x-www-form-urlencoded” mime type. This is the same format used by standard HTTP form post actions, so most server side processors understand how to parse form posts.

Controlling Your Events ​

You may control the processing of these actions by including optional semicolon-separated name/value pairs in the Data property. Valid values are:

Data ParametersDescription
request-timeoutA value from 30 to 180. This is the number of seconds the AlphaTrust® e-Sign HTTP POST or GET should wait for a response from your listener URL before timing out. The default value is 30 seconds.

Example: Data="request-timeout=60;"
required-response-textA value that AlphaTrust® e-Sign will expect to receive from your listener to indicate that you have processed the POST or GET successfully. If a value is set here, you must use a mime type of "text/plain" in your response to the AlphaTrust® e-Sign GET or POST. Use the HTTP Content-Type header (i.e. "Content-Type: text/plain"). If you do not set this value then AlphaTrust® e-Sign will only look for an HTTP status code between 200 and 299 inclusive to indicate success. If you do set this value then both a success status code and "required-response-text" value match is required. This value is case-insensitive.

Example: Data="request-response-text=RECEIVED;"
retry-limitA value representing the maximum number of minutes to retry status update messages in the case of failed (unsuccessful) GET or POST requests to your listener. Valid values are between 30 and 10080 (7 days), inclusive. If you do not specify this value then a default value globally configured for the AlphaTrust® e-Sign installation is used. The value, by default, is "4320" (3 days). The interval between retries is 5 minutes, unless a different globally configured value is set for AlphaTrust® e-Sign (on-prem/in-stack option only).

Example: Data="retry-limit=1440;"

Common Data Elements ​

Below are common data elements that will be included in all Participants Event Subscriptions.

NameValue
TransIDThe TransID is a standard 10 digit ID used for a transaction as discussed elsewhere. Example: 1234567890
PartIDThe PartID is a standard 10 digit ID used for a participant as discussed elsewhere. Example: 1234567890
PartStatusThe PartStatus will be one of the following one-digit integer values:
  • 2 Pending
  • 4 Complete
  • 6 Email sent - Participant has been notified by email but is still in the Pending status. You will receive a notification every time an email notice is sent to the participant. So if there are three email notices sent, then you will receive three status update messages related to it. This value is only valid for PartStatus and SigStatus.
  • 7 Closed
  • 8 Cancelled
  • 9 Expired
TXStatusThe TXStatus will be one of the following one-digit integer values:
  • 2 Pending
  • 4 Complete
  • 7 Closed
  • 8 Cancelled
  • 9 Expired
  • 10 Voided
PartAccessTokenDEPRECATED
ps_securitytokenguid

Status Change ​

You can subscribe to Document status change events by adding a Workflow Action to the Document.

The data elements sent in the GET or POST are all the common data elements plus the following:

NameValue
EventTypedocument

WARNING

If the Participant's CancelledTaskBehaviorType is set to AutomaticCancel or DisplayCancelOrSuspendOption and they cancel a transaction, the notification will be sent and the returned TXStatus and DocStatus values for the transaction will be 8. If the Participant's CancelledTaskBehavior is set to AutomaticSuspend, no notification will be sent because the status stays as a 2 which is the pending status. Likewise, if the Participant's CancelledTaskBehavior is set to DisplayCancelOrSuspend and they choose to only suspend their process after hitting the initial cancel button, no notification will be sent because the status stays in a 2 pending status.

csharp
document = new DocumentInsertModel()
           {
               ...
               WorkflowActions = new List<object>
                                 {
                                     new DocumentWorkflowActionModel()
                                     {
                                         Type = DocumentWorkflowActionModel.TypeEnum.SubscribeToStatusChangeNotificationsByPost,
                                         Data = "required-response-text=RECEIVED;retry-limit=1440",
                                         Url = "https://myapp.mydomain.com/statuslistener.php"
                                     }
                                 }
               ...
           }

A completed document from that uses the above code would see something like the following as the posted status notification values:

TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4EventType=document&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Likewise, if the document was using a SubscribeToStatusChangeNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4EventType=document&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Skipped Document ​

You can subscribe to Skipped-Document events by adding a Workflow Action to the Document.

The data elements sent in the GET or POST are all the common data elements plus the following:

NameValue
PartIDThe PartID is a standard 10 digit ID used for a document as discussed elsewhere and is the participant ID for the participant that skipped the document.

Example: 1234567890
EventTypeskipped-document
csharp
document = new DocumentInsertModel()
           {
               ...
               WorkflowActions = new List<object>
                                 {
                                     new DocumentWorkflowActionModel()
                                     {
                                         Type = DocumentWorkflowActionModel.TypeEnum.SubscribeToSkippedDocumentNotificationsByPost, //or ...ByGet
                                         Data = "required-response-text=RECEIVED;retry-limit=1440",
                                         Url = "https://myapp.mydomain.com/statuslistener.php"
                                     }
                                 }
               ...
           }

A completed document from that uses the above code would see something like the following as the posted status notification values:

TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4&EventType=skipped-document&PartID=1234567890&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Likewise, if the document was using a SubscribeToSkippedDocumentNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4&EventType=skipped-document&PartID=1234567890&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Document Seal ​

You can subscribe to Document Seal events by adding a Workflow Action to the Document.

The data elements sent in the GET or POST are all the common data elements plus the following:

NameValue
EventTypedocument-seal
csharp
document = new DocumentInsertModel()
           {
               ...
               WorkflowActions = new List<object>
                                 {
                                     new DocumentWorkflowActionModel()
                                     {
                                         Type = DocumentWorkflowActionModel.TypeEnum.SubscribeToSealStatusNotificationsByPost,
                                         Data = "required-response-text=RECEIVED;retry-limit=1440",
                                         Url = "https://myapp.mydomain.com/statuslistener.php"
                                     }
                                 }
               ...
           }

A completed document from that uses the above code would see something like the following as the posted status notification values:

TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4EventType=document-seal&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Likewise, if the document was using a SubscribeToSealStatusNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4EventType=document-seal&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Document Certification ​

WARNING

Document Certification has been deprecated in v5.16+.

You can subscribe to Document Certification events by adding a Workflow Action to the Document.

The data elements sent in the GET or POST are all the common data elements plus the following:

NameValue
EventTypedocument-certify
csharp
document = new DocumentInsertModel()
           {
               ...
               WorkflowActions = new List<object>
                                 {
                                     new DocumentWorkflowActionModel()
                                     {
                                         Type = DocumentWorkflowActionModel.TypeEnum.SubscribeToCertifyStatusNotificationsByPost,
                                         Data = "required-response-text=RECEIVED;retry-limit=1440",
                                         Url = "https://myapp.mydomain.com/statuslistener.php"
                                     }
                                 }
               ...
           }

A completed document from that uses the above code would see something like the following as the posted status notification values:

TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4EventType=document-certify&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Likewise, if the document was using a SubscribeToCertifyStatusNotificationsByGet method type, the posted status notification value might look something like this:

https://myapp.mydomain.com/statuslistener.aspx?TransID=1234567890&DocID=1234567890&TXStatus=2&DocStatus=4EventType=document-certify&ps_securitytoken=4bf44fb0-f695-40b5-821d-c22273e11c30

Copyright © 1998-present AlphaTrust