The notification call back messages are sent using the
TrustSignNotification message protocol using the POST method. The messages sent are based on
triggers defined in the sign order. Messages are transmitted as XML files of predefined structure and convey a specific type of information to the receiving system.
Here you can find shema defining the XML message structure:
E-Signing notification XSD.
Note: The E-Signing notification service expects an OK response within 5 seconds. If that is not received, the service will try to resend the message. To avoid resending of messages, it is important that the customer doesn’t implement any functions (e.g GetSDO) prior to sending a response OK.
TrustSignNotification
| OrderID | The OrderID sent by the customer. | MinLength = 1 MaxLength = 80 |
| MerchantID | This value represents the calling customer. The customer gets this value upon configuration in E-Signing. | NA |
| Time | The message creation time. | NA |
| OrderNotification |
Read more about OrderNotification. | NA |
| StepNotification | Read more about StepNotification. | NA |
OrderNotification
A sign order passes through different states during the normal lifecycle. The state of a sign order is indicated by a unique status identifier. For each status change, E-Signing triggers are sent to notify subscribing systems of the associated events.
OrderNotification messages always have a trigger whose purpose is to inform the message recipient of the event that caused the notification to be sent.
| Trigger | Trigger that is the source of notification (details in following table). | NA |
| Reject text | Optional feedback from the signer. Only included when a signer provides feedback after rejecting a sign process. | NA |
| Trigger info | Code explaining why the trigger was sent. | NA |
The following table details the triggers listeners can subscribe to:
| OnOrderCancellation | A sign order has been cancelled by the owning customer. |
| OnOrderCompletion | Sign order processing is complete. |
| OnOrderRejection | Sign order has been rejected by a signer (RejectText is optional feedback from signer). |
| OnOrderExpiration | Sign order deadline has passed. |
| OnOrderFailed | The sign order has failed, and the sign order status is now
Failed. |
A typical
OrderNotification may look like the following xml example
<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification
xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<OrderID>b5-4ever</OrderID>
<MerchantID>xxxx</MerchantID>
<Time>2093-07-13T21:49:57</Time>
<OrderNotification>
<Trigger>OnOrderCompletion</Trigger>
</OrderNotification>
</TrustSignNotification>
StepNotification
StepNotification messages are published by E-Signing whenever the state of a step changes. For each status change, a trigger is sent and a message is transmitted to all subscribing applications.
The member elements are shown in the following table.
| Trigger | Trigger that is the souce of notification (details in following table) | NA |
| StepNumber | The number of the affected Step. | NA |
| StepReferences | A list of available references in the current step. See details below. | Optional |
StepReferences
StepReferences is optional and may only occur in
StepNotifications with the
OnStepReady trigger.
| StepReference/LocalSignerReference | A reference identifying the signer bound to the step | NA |
| StepReference/SignURL | The sign URL to the currently active step. | NA |
The following table details the triggers listeners can subscribe to:
| OnStepCompletion | A step within a sign order has been completed. |
| OnStepReady | A step within an order is ready for processing.
|
| OnStepExpiration | A step deadline has passed. |
A typical
StepNotification may look like the following XML example:
<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<OrderID>b5-4ever</OrderID>
<MerchantID>xxxx</MerchantID>
<Time>2093-07-13T21:49:57</Time>
<StepNotification>
<Trigger>OnStepCompletion</Trigger>
<StepNumber>1</StepNumber>
</StepNotification>
</TrustSignNotification>
SigningProcessNotification
SigningProcessNotification messages are published by E-Signing whenever the state of a sign process changes. For each status change, a trigger is sent and a message is transmitted to all subscribing applications.
The following table displays all the elements of a
SigningProcessNotification.
| Trigger | The event whose occurrence caused the creation of this notification. | NA |
| StepNumber | The step within which the affected sign process is defined. | NA |
| LocalSignerReference | A reference to indicate the signer that provoked a sign process event (see own details below). | NA |
| TargetReferences | A reference to the affected document(s) in the notification. See details in
TargetReferences below. | NA |
| RejectText | Optional feedback from the signer. Only included when a signer provides feedback after rejecting a sign process. | NA |
| Timestamp | The time the event occurred. | NA |
TargetReferences
Each defined document is issued in a separate
TargetReference.
| TargetReference/LocalDocumentReference | The reference to the actual document targeted by the notification message. | NA |
| TargetRefererce/SignURL | Optional sign URL. | NA |
A typical
SigningProcessNotification may look like the following XML example:
<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<OrderID>b5-4ever</OrderID>
<MerchantID>xxxx</MerchantID>
<Time>2093-07-13T21:49:51</Time>
<SigningProcessNotification>
<Trigger>OnSignProcessCompletion</Trigger>
<StepNumber>1</StepNumber>
<LocalSignerReference>LSR_1</LocalSignerReference>
<TargetReferences>
<TargetReference>
<LocalDocumentReference>D_1</LocalDocumentReference>
</TargetReference>
</TargetReferences>
</SigningProcessNotification>
</TrustSignNotification>
SigningProcessNotification messages vary in structure and content. This next example illustrates a message for sign processes in the
Active state. Note that the
TargetReference element in the message now also contains a
SignURL.
<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification
xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<OrderID>b5-4ever</OrderID>
<MerchantID>1001</MerchantID>
<Time>2093-07-13T21:49:51</Time>
<SigningProcessNotification>
<Trigger>OnSignProcessReady</Trigger>
<StepNumber>1</StepNumber>
<LocalSignerReference>LSR_1</LocalSignerReference>
<TargetReferences>
<TargetReference>
<LocalDocumentReference>D_1</LocalDocumentReference>
<SignURL>https://host/sign/13579</SignURL>
</TargetReference>
<TargetReference>
<LocalDocumentReference>D_2</LocalDocumentReference>
<SignURL>https://host/sign/97531</SignURL>
</TargetReference>
</TargetReferences>
</SigningProcessNotification>
</TrustSignNotification>
Here is yet another example, this time for rejected sign processes.
<?xml version="1.0" encoding="UTF-8"?>
<TrustSignNotification
xmlns="http://www.bbs.no/tt/trustsign/2009/05/tnm#"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<OrderID>b5-4ever</OrderID>
<MerchantID>1001</MerchantID>
<Time>2093-07-13T21:49:51</Time>
<SigningProcessNotification>
<Trigger>OnSignProcessRejection</Trigger>
<StepNumber>1</StepNumber>
<LocalSignerReference>LSR_1</LocalSignerReference>
<TargetReferences>
<TargetReference>
<LocalDocumentReference>D_1</LocalDocumentReference>
</TargetReference>
</TargetReferences>
<RejectText>Lorem ipsum</RejectText>
<Timestamp>2093-07-13T21:49:37</Timestamp>
</SigningProcessNotification>
</TrustSignNotification>
