In order to use this option, you have to provide the LiveConsent Support Team, a valid default HTTPS URL of your callback script (default_callback_url).
After a specified action (see the table below), LiveConsent will call the callback URL, defined on the client side, for notification/updates.

Parameters will be sent using the GET method. The parameters are:

  • requestId: LiveConsent unique id of the created request
  • status: status code; depending on the value of the status code, the notification corresponds to an action on the request or to the recipients (see table below)
  • recipientEmail: email of the recipient
  • approverEmail (OBSOLETE): email of the recipient
  • recipientPhone: new phone number of the recipient
  • statusInfo: depending of the retruned status value, statusInfo will contain:
    • message_id;
    • SMTP status code;
  • eventDate: date of the event (YYYY-MM-DDThh:mm:ssZ, format ISO 8601)
  • errorCode: check the error code list in Appendix 1

Parameters are described in the following table:

ParameterValueDescription
requestId string Unique id of LiveConsent Request
status integerStatus code
recipientEmail stringEmail of the recipient (URL encoded)
approverEmail (OBSOLETE)stringEmail of the recipient (URL encoded)
statusInfo string- message_id for status = 18
- SMTP status code for status = 16
recipientPhone stringNew phone number of the recipient (URL encoded)
eventDate stringdate of the event (URL encoded)
YYYY-MM-DDThh:mm:ssZ, format ISO 8601)
errorCode stringCheck the error code list in Appendix 1

Status Code values Table:

Value for "status"DescriptionComments
2Request state is draftPossible values for requests
3Request is livePossible values for requests
4Request completed (signed)Possible values for requests
5Request has been declined by a signerPossible values for requests
6Request has been abandoned by requesterPossible values for requests
7Request has expiredPossible values for requests
8Error in request processingPossible values for requests
13Request opened by recipientPossible values for recipients
14Request signed by signerPossible values for recipients
15Request rejected by signerPossible values for recipients
16Error in email deliveryPossible values for recipients
17Recipient requests a modification of the phone numberPossible values for recipients
18New message added to requestPossible values for recipients

For status range 2-8, there will be no recipientEmail (approverEmail), statusInfo and recipientPhone values.
Values for eventDate, recipientEmail (approverEmail) and recipientPhone are URL encoded.

The callback URL must return OK (echo „OK”), because LiveConsent has to know that the callbacks have been supplied successfully. If your server is down, LCS will retry to send the callback 10 more times (2 minutes, 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 12 hours, 24 hours).

📘

Observation

On the client application side, IP restriction is recommended. Our technical service will provide, to the developer of the client application, the IP values.

Callback Examples

Example of a callback with request updates:

https://your.website.url/status_update.php?requestId=FD21GT&status=4&recipientEmail=&statusInfo=&recipientPhone=&approverEmail=&eventDate=2020-07-20T15%3A50%3A08Z&errorCode=0

Example of a callback with recipient updates:

https://your.website.url/status_update.php?requestId=FD21GT&status=14&recipientEmail=name%2Btest%40email.com&statusInfo=&recpientPhone=&approverEmail=name%2Btest%40email.com&eventDate=2020-07-20T15%3A50%3A08Z&errorCode=0

Example of a callback with an email delivery error:

https://your.website.url/status_update.php?requestId=FD21GT&status=16&recipientEmail=name%2Btest%40email.com&statusInfo=5.5.0&recpientPhone=&approverEmail=name%2Btest%40email.com&eventDate=2020-07-20T15%3A50%3A08Z&errorCode=0

Example of a callback for a new message:

https://your.website.url/status_update.php?requestId=FD21GT&status=18&recipientEmail=name%2Btest%40email.com&statusInfo=2&recpientPhone=&approverEmail=name%2Btest%40email.com&eventDate=2020-07-20T15%3A50%3A08Z&errorCode=0

Example of a callback with a request for the modification of the recipient’s phone number:

https://your.website.url/status_update.php?requestId=FD21GT&status=17&recipientEmail=name%2Btest%40email.com&statusInfo=&recipientPhone=%2B3312345678&approverEmail=name%2Btest%40email.com&eventDate=2020-07-20T15%3A50%3A08Z&errorCode=0