Setting Up Callback Notifications

Callback Event Notifications enable you to be automatically notified of events that pertain to a package. When a specific event occurs, the system will automatically send a message to a destination that you have chosen.

Callback Notifications

Setting Up Callback Notifications

Before moving on to the code, it would be good to know all of the notifications available. As you can see in the image above, there are several.

Event Description JSON Payload
DOCUMENT_SIGNED A document was signed, or Consent and/or Disclosure Agreements were accepted. { "name": "DOCUMENT_SIGNED", "sessionUser": "...", "packageId": "......", "documentId": "......", (max 256 chars) "createdDate": "2017-05-02T20:17:58.408Z" }
DOCUMENT_VIEWED A document was viewed. { "name": "DOCUMENT_VIEWED", "sessionUser": "...", "packageId": "......", "documentId": "......", (max 256 chars) "createdDate": "2017-05-02T20:17:58.408Z" }
EMAIL_BOUNCE

An email has bounced. The bounce types are the following:

  • "BOUNCE" (a hard bounce)
  • "COMPLAINT" (a soft bounce)
  • "OOTO" (out-of-the-office)
  • "UNKNOWN"
 { "name": "EMAIL_BOUNCE", "sessionUser": "...", "packageId": "......", "message": "bounce type", "createdDate": "2017-05-02T20:17:58.408Z" }
KBA_FAILURE There has been a KBA Authentication failure { "name": "KBA_FAILURE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_ACTIVATE A package was moved from the status DRAFT or DELETED to the status SENT. By default, a package is created in the DRAFT state, and is moved to the SENT state when it's ready to be processed by signers. { "name": "PACKAGE_ACTIVATE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_ARCHIVE A callback notification indicates that a package has been archived. { "name": "PACKAGE_ARCHIVE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_ATTACHMENT A callback notification indicates that a signer has uploaded an attachment. { "name": "PACKAGE_ATTACHMENT", "sessionUser": "...", "packageId": "......", "message": "attachment name", (max 255 chars) "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_COMPLETE A package has completed the signing process. { "name": 'PACKAGE_COMPLETE', "sessionUser": '...', "packageId": '......', "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_CREATE A package has been created. Thus the Originating System can record ValidSign's package ID, together with the Originating System's transaction ID. { "name": "PACKAGE_CREATE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_DEACTIVATE A package's status has changed from SENT to DRAFT.     { "name": "PACKAGE_DEACTIVATE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_DECLINE A recipient has declined to sign a package, and has specified a reason for doing so, The Originating System can use that reason to determine the next step for the package. { "name": "PACKAGE_DECLINE", "sessionUser": "...", "packageId": "......", "message": "decline reason", (max 4000 chars) "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_DELETE A package has been deleted from the ValidSign system. { "name": "PACKAGE_DELETE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_EXPIRE A package has exceeded its expiration date. { "name": "PACKAGE_EXPIRE", "sessionUser": "...", "packageId": "...", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_OPT_OUT A recipient has opted out of signing a package electronically, and has specified a reason for doing so. The Originating System can use that reason to determine the next step for the package. { "name": "PACKAGE_OPT_OUT", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_READY_FOR_COMPLETE A package has been marked as DO_NOT_AUTOCOMPLETE. An action by the sender will be required to complete the package. { "name": "PACKAGE_READY_FOR_COMPLETE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_RESTORE A package was trashed, but is being moved back to the state it was in before it was trashed. { "name": "PACKAGE_RESTORE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_TRASH A package was moved to the trash folder in ValidSign's Inbox (status = TRASH). { "name": "PACKAGE_TRASH", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
ROLE_REASSIGN A signer has delegated their signature to another signer. { "name": "ROLE_REASSIGN", "sessionUser": "...", "packageId": "......", "newRoleId": "......", (max 255 chars) "createdDate": "2017-05-02T20:17:58.408Z" }
SIGNER_COMPLETE A signer has completed signing all documents. { "name": "SIGNER_COMPLETE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
SIGNER_LOCKED A callback notification indicates that a signer has been locked out due to repeated SMS/Q&A authentication failures. { "name": "SIGNER_LOCKED", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }
TEMPLATE_CREATE A callback notification indicates that a template has been created. { "name": "TEMPLATE_CREATE", "sessionUser": "...", "packageId": "......", "createdDate": "2017-05-02T20:17:58.408Z" }

 

The following code samples can be used to set the callback URL, callback key, and subscribe you to three different event notifications.

POST /api/callback

{
    "url": "https://www.example.com/callbackNotifications",
    "key": "your_optional_security_key",
    "events":
    [
        "PACKAGE_CREATE",
        "PACKAGE_DECLINE",
        "PACKAGE_COMPLETE"
    ]
}
eslClient.getEventNotificationService().register(newEventNotificationConfig("https://www.example.com/callbackNotifications")
   .withKey("your_optional_security_key")
   .forEvent(NotificationEvent.PACKAGE_CREATE)
   .forEvent(NotificationEvent.PACKAGE_DECLINE)
   .forEvent(NotificationEvent.PACKAGE_COMPLETE));
eslClient.getEventNotificationService().register(newEventNotificationConfig("https://www.example.com/callbackNotifications")
   .withKey("your_optional_security_key")
   .forEvent(NotificationEvent.PACKAGE_CREATE)
   .forEvent(NotificationEvent.PACKAGE_DECLINE)
   .forEvent(NotificationEvent.PACKAGE_COMPLETE));