Skip to content

Web hooks : generalities

Web hooks are http POST server-to-server requests made by Trust and Sign to the IT client, containing the minimal information to "follow" the progress of the files in a faster way than periodic tasks periodic tasks querying the status of the files.

The web hook requests are triggered shortly after the events, and can group up to 10 events. For each folder, the notifications are POSTed in chronological order.

Web hooks are a special type of notification, and are configured from the Trust and Sign Center for each version of the path:

  • url to use for the POST (common to all events and folders)
  • should we include the external information of the folder in the POSTed data ?
  • optional http header (typically to add static authentication)

Constraints to receive web-hooks:

  • The url to the IT client must be of type https:// on standard port 443, with a public hostname. The certificate presented by the server must be valid and recognized by the standard CAs.
  • Depending on your firewall, you will have to allow the IP address of the server sending the web hooks (77.72.89.144 for all environments then 178.20.69.130 in integration and 193.239.193.94 in production).
  • the server must process the request quickly (less than 20 seconds, regardless of the number of events contained in the POST), and the http response must have a status of 2xx (success). Otherwise, the POST will be considered as a failure (including in case of http redirect response with status 3xx).
  • in case of server or network unavailability, the POST is considered failed.
  • failed POSTs are retried later (with potentially more events); the period is doubled with each attempt, with a maximum duration of about 12 hours. After that, the notifications are destroyed and will not be no longer POSTed.
  • the IT client server must be able to manage duplicate notifications; each notification has each notification has an id for this purpose. If for example Trust and Sign manages to POST the data but does not receive the response due to a network problem, these failed notifications will be retried and therefore received twice by the client IT.

Content of the data of the web request hook POST

The http POST made by Trust and Sign is of type Content-Type: application/x-www-form-urlencoded and the content of the request contains the notifications parameter which is an array of JSON objects, each object being a notification. The array can be quite large (up to 10 events).

Other additional parameters could exist, they should be ignored.

Example of a notifications array (decoded content from URL-encoded format):

{
    "notifications": [
        {
            // Unique identifier of the notification, and date of the event
            "id": 154567,
            "date": "2018-10-31T08:46:02.956Z",
            // Event occurred (see list below)
            "event": "CREATION",
            // Trust and Sign identifier of the file
            "clientFileUuid": "00000001-1234-5678-abcd-aaaaaaaaaaaa",
            // Optional: external identifier of the file (if defined in creation)
            "externalId": "test-extId1",
            // Optional (depending on the configuration): list of external information of the folder
            "externalInfo": {
                "test-key": "test-value1"
            }
        },
        {
            "id": 167842,
            "date": "2018-10-31T08:46:02.956Z",
            "event": "SIGNATURE",
            "clientFileUuid": "00000002-1234-5678-abcd-aaaaaaaaaaaa",
            "externalInfo": {
                "test-key": "test-value2"
            },
            "externalId": "test-extId2"
        },
        {
            "id": 167845,
            "date": "2024-10-31T08:46:02.956Z",
            "event": "DOCUMENT_SUBMITTED_FOR_PARTICIPANT",
            "clientFileUuid": "00000002-1234-5678-abcd-aaaaaaaaaaab",
            // Optional: participant id when event is DOCUMENT_SUBMITTED_FOR_PARTICIPANT or ALL_MANDATORY_DOCUMENT_SUBMITTED_FOR_PARTICIPANT
            "participantUuid": "fa03c1f3-2a7c-4a2f-b041-35be3c48b9d6",
            // Optional: task id when event is DOCUMENT_SUBMITTED_FOR_PARTICIPANT
            "taskId": "12345"
        },
        {
            "id": 167846,
            "date": "2024-12-26T14:43:55.495Z",
            "event": "ALL_MANDATORY_DOCUMENT_SUBMITTED_FOR_PARTICIPANT",
            "clientFileUuid": "0194036c-0798-703f-946c-4c2a3ecf0986",
            // Optional: participant id when event is DOCUMENT_SUBMITTED_FOR_PARTICIPANT or ALL_MANDATORY_DOCUMENT_SUBMITTED_FOR_PARTICIPANT
            "participantUuid": "0194036c-079e-7e2a-a88b-a09691dca480"
        },
        {
            "id": 167847,
            "date": "2024-10-31T08:46:02.956Z",
            "event": "CLIENT_FILE_CLOSED",
            "clientFileUuid": "00000002-1234-5678-abcd-aaaaaaaaaaab",
            // Optional: client file state when event is CLIENT_FILE_CLOSED
            "clientFileState": "REJECTED",
            // Optional: rejection reason when event is CLIENT_FILE_CLOSED and clientFileState is REJECTED
            "rejectionCause": "EXPIRED"
        },
        {
            "id": 167848,
            "date": "2025-01-30T13:22:58.991495Z",
            "event": "IDENTITY",
            "clientFileUuid": "00000002-1234-5678-abcd-aaaaaaaaaaab",
            // Optional: LiveCheck request status when event is IDENTITY (possible values DISABLED | SENT | NOT_SENT)
            "liveCheckRequest": "DISABLED",
            // Optional: control summary status when event is IDENTITY (possible values OK | KO)
            "autoControls": "KO"
        }
    ]
}

List of web hook notification events

Event Description
CREATION Opening / creating a file
SIGNATURE Signature of document(s) by a participant
SIGNATURE_BY_ALL Signature of all participants
SUSPENDED Suspension of file
FINALIZATION Finalization of the file by all participants
ACCEPTATION File Acceptance
IDENTITY An identification task has just been done
LIVE_CHECK_STARTED A LiveCheck request has been successfully sent
IDENTITY_APPROVED Identity verification approved via LiveCheck
IDENTITY_APPROVED_READY_TO_SIGN LiveCheck identity verification has been approved and the user can now sign the file.
IDENTITY_APPROVED_READY_TO_ADD_DOCUMENTS LiveCheck identity verification has been approved and the user can now submit the documents.
IDENTITY_REJECTED Identity verification rejected via LiveCheck
IDENTIFICATION_ERROR An identification task has just passed in error (AR24, LIN, or by API)
OTP_SENT An OTP code was just sent
DOCUMENT_SUBMITTED_FOR_PARTICIPANT A document has been submitted by participant
ALL_MANDATORY_DOCUMENT_SUBMITTED_FOR_PARTICIPANT All mandatory documents for participant have been submitted
CLIENT_FILE_FINALIZATION File is finalized
WAITING_TO_BE_VALIDATED File is waiting for validation
REOPEN Reopen file for document
REOPEN_FOR_SIGNATURES Reopen File for Signature
REOPEN_FOR_DOCUMENTS_AND_SIGNATURES File Reopening for Document and Signature
REJECTION_AFTER_VALIDATION Rejection after Validation
EXPIRED Reject after expiration
TECHNICAL_PROBLEM Reject after technical problem
USER_SIGNATURE_REFUSAL Reject after refusal to sign
CANCELED Reject after cancellation
TOO_MANY_OTP_TRIES Reject after OTP limit reached
DOC_SUBMISSION_ERROR Reject after document submission error
CLIENT_FILE_CLOSED The file is closed. The payload then contains the clientFileState attribute with the value ACCEPTED or REJECTED. If REJECTED, a second rejectionCause attribute indicates the cause whose list of possible values is here. This notification is a generic one that encompasses previous rejections and ACCEPTATION.
UNBLOCKING Unblocking of file
UNBLOCKING_REOPEN Reopen after Unlocking
UNBLOCKING_REFUSAL Rejection after Unlocking
SERVICE_PARTICIPANTS_RECOVERY End of maintenance

Note: When the IDENTITY_APPROVED_READY_TO_SIGN and IDENTITY_APPROVED_READY_TO_ADD_DOCUMENTS events are sent then the IDENTITY_APPROVED event will not be sent.