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 (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