Callback Event Notifications allow you to be automatically notified of events that are related to a package or transactions. When a specific event occurs, the system automatically sends a message to a destination that you specify.

Location in the UI

To find the callback area from the UI, log into Conga Sign and click Admin > Event Notification. After you run your code, you will be able to check here to make sure it ran successfully. 

Available Notifications

The following table lists the notifications that are available:

In the following table:

  • The maximum size for all sessionUser field is 255 characters.
  • The maximum size for all packageId field is 255 characters.
  • The sessionUser field depends on whether or not the event was generated by a sender, or by a signer. Sender triggered events will have the sender ID. Signer triggered events will have the signer ID.
EventEvent DescriptionJSON Payload
DOCUMENT_SIGNEDA 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_VIEWEDA document was viewed.{ "name": "DOCUMENT_VIEWED","sessionUser": "...","packageId": "......","documentId": "......", (max 256 chars)"createdDate": "2017-05-02T20:17:58.408Z" }
EMAIL_BOUNCEAn 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" }
BA_FAILUREThere was a KBA Authentication failure.{ "name": "KBA_FAILURE","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_ACTIVATEA 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_ARCHIVEA callback notification indicates that a package has been archived.{ "name": "PACKAGE_ARCHIVE","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_ATTACHMENTA 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_COMPLETEA package has completed the signing process. If there are multiple signers then the "sessionUser": "...", will be the signer ID of the last signer to sign.{ "name": 'PACKAGE_COMPLETE',"sessionUser": '...',"packageId": '......',"createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_CREATEA package has been created. Thus the Originating System can record Conga Sign's package ID, together with the Originating System's transaction ID.{ "name": "PACKAGE_CREATE","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_DEACTIVATEA package's status has changed from SENT to DRAFT.{ "name": "PACKAGE_DEACTIVATE","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_DECLINEA 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_DELETEA package has been deleted from the Conga Sign system.{ "name": "PACKAGE_DELETE","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_EXPIREA package has exceeded its expiration date.{ "name": "PACKAGE_EXPIRE","sessionUser": "...","packageId": "...","createdDate": "2017-05-02T20:17:58.408Z" }
PACKAGE_READY_FOR_COMPLETEA 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_RESTOREA 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_TRASHA package was moved to the trash folder in Conga Sign's Inbox (status = TRASH).{ "name": "PACKAGE_TRASH","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }
ROLE_REASSIGNA 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_COMPLETEA signer has completed signing all documents.{ "name": "SIGNER_COMPLETE","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }
SIGNER_LOCKEDA 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_CREATEA callback notification indicates that a template has been created.{ "name": "TEMPLATE_CREATE","sessionUser": "...","packageId": "......","createdDate": "2017-05-02T20:17:58.408Z" }

Receiving Event Notifications

After registering to get notifications for one or more event types, you need only listen for the associated notifications. When a relevant event is triggered, Conga Sign sends an HTTP POST to your registered URL. That message contains a payload in JSON format, describing the event that triggered the notification. The callback key you registered is passed through the Authorization header as "Basic {callbackKey}". You have use this to make sure you are receiving notifications that contain the shared secret, so you know you are not getting spoof calls and can react accordingly.

Here are some examples of callback payloads:

Package was Created
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_CREATE","sessionUser":"18EZDL44xgsX","packageId":"wVdZEaPD2igwUnFGJBjDD0dpO7k=","message":null,"documentId":null,"createdDate":"2018-06-30T20:04:55.384Z"}
Package was Sent
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_ACTIVATE","sessionUser":"18EZDL44xgsX","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:09:50.425Z"}
Signer 1 accepted consent document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"default-consent","createdDate":"2018-06-30T20:10:51.002Z"}
Signer 1 completed a document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691","createdDate":"2018-06-30T20:12:12.256Z"}
Signer 1 completed signing package
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"SIGNER_COMPLETE","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:12:12.272Z"}
Package was Complete
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_COMPLETE","sessionUser":"e00696ec-d6f5-4feb-89c5-a5ce002a6c66","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:15:01.038Z"}
CODE

To set up Callback Notifications

The examples below demonstrate three approaches to setup callback notifications with webhooks.

Basic Authentication

HTTP Request

PUT /api/callback/register
CODE

HTTP Headers

Accept: application/json   Content-Type: application/json
CODE

Request Payload

 {
 "callbackUrl":"https://your.domain/your.callback.listener.endpoint",
 "authType": "Basic",
 "username": "your.username",
 "password": "your.password"
}
CODE

All fields are required when creating or updating the callback. When you provide an empty string for the callbackUrl, it disables the callback.

Response Payload

{
 "callbackUrl":"https://your.domain/your.callback.listener.endpoint",
 "authType": "Basic",
 "username": "your.username",
 "password": "your.password"
}
CODE

Bearer Token Authentication

HTTP Request

PUT /api/callback/register
CODE

HTTP Headers

Accept: application/json   Content-Type: application/json
CODE

Request Payload

{
 "callbackUrl":"https://your.domain/your.callback.listener.endpoint",
 "authType": "Bearer",
 "bearerToken": "your.bearer.token"
}
CODE

All fields are required when creating or updating the callback. When you provide an empty string for the callbackUrl, it disables the callback.

Response Payload

{
 "callbackUrl":"https://your.domain/your.callback.listener.endpoint",
 "authType": "Bearer",
 "bearerToken": "your.bearer.token"
}
CODE

No Authentication

HTTP Request

PUT /api/callback/register
CODE

HTTP Headers

 Accept: application/json   Content-Type: application/json
CODE

Request Payload

{
 "callbackUrl":"https://your.domain/your.callback.listener.endpoint",
 "authType": "None"
}
CODE

All fields are required when creating or updating the callback. When you provide an empty string for the callbackUrl, it disables the callback.

Response Payload

{
 "callbackUrl":"https://your.domain/your.callback.listener.endpoint",
 "authType": "None"
}
CODE