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:

Parameter

Value

Description

requestId

string

Unique id of LiveConsent Request

status

integer

Status code

recipientEmail

string

Email of the recipient (URL encoded)

approverEmail (OBSOLETE)

string

Email of the recipient (URL encoded)

statusInfo

string

  • message_id for status = 18
  • SMTP status code for status = 16

recipientPhone

string

New phone number of the recipient (URL encoded)

eventDate

string

date of the event (URL encoded)
YYYY-MM-DDThh:mm:ssZ, format ISO 8601)

errorCode

string

Check the error code list in Appendix 1

Status Code values Table:

Value for "status"

Description

Comments

2

Request state is draft

Possible values for requests

3

Request is live

Possible values for requests

4

Request completed (signed)

Possible values for requests

5

Request has been declined by a signer

Possible values for requests

6

Request has been abandoned by requester

Possible values for requests

7

Request has expired

Possible values for requests

8

Error in request processing

Possible values for requests

13

Request opened by recipient

Possible values for recipients

14

Request signed by signer

Possible values for recipients

15

Request rejected by signer

Possible values for recipients

16

Error in email delivery

Possible values for recipients

17

Recipient requests a modification of the phone number

Possible values for recipients

18

New message added to request

Possible 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 (5 minutes, 10 minutes, 15 minutes, 30 minutes, 45 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&recpientEmail=&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=14&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&recpientEmail=name%2Btest%40email.com&statusInfo=&recipientPhone=%2B3312345678&approverEmail=name%2Btest%40email.com&eventDate=2020-07-20T15%3A50%3A08Z&errorCode=0