Aller au contenu

Web hooks : généralités

Les web hooks sont des requêtes http POST serveur à serveur, réalisées par Trust and Sign vers l'IT client, contenant les informations minimales pour "suivre" l'avancement des dossiers de manière plus rapide que des tâches périodiques requêtant l'état des dossiers.

Les requêtes web hook sont déclenchées peu après les événements, et peuvent regrouper jusqu'à 10 événements. Pour chaque dossier, les notifications sont POSTées dans l'ordre chronologique.

Les web hooks sont un type particulier de notification, et sont configurés depuis l'interface Trust and Sign Center pour chaque version de parcours :

  • url à utiliser pour le POST (commune à tous les événements et dossiers)
  • doit-on inclure les informations externes du dossier dans les données POSTées ?
  • header http optionnel (typiquement pour ajouter une authentification statique)

Contraintes pour recevoir les web-hooks :

  • L'url vers l'IT client doit être de type https:// sur le port standard 443, avec un nom d'hôte public. Le certificat présenté par le serveur doit être valide et reconnu par les AC standard.
  • Selon votre firewall, vous devrez autoriser l'adresse IP du serveur envoyant les web hooks (77.72.89.144 pour tous les environnements puis 178.20.69.130 en intégration et 193.239.193.94 en production).
  • le serveur doit traiter la requête rapidement (moins de 20 secondes, indépendamment du nombre d'événements contenus dans le POST), et la réponse http doit avoir un status 2xx (succès). Dans le cas contraire, le POST sera considéré comme un échec (y compris dans le cas d'une réponse type redirect avec status 3xx).
  • en cas d'indisponibilité du serveur ou du réseau, le POST est considéré en échec.
  • les POST en échec sont retentés ultérieurement (avec potentiellement davantage d'événements) ; la période est doublée à chaque essai, avec une durée maximum de l'ordre de 12h. Au delà, les notifications sont détruites et ne seront plus POSTées.
  • le serveur de l'IT client doit être à même de gérer les doublons de notifications ; chaque notification dispose d'un id pour ce faire. Si par exemple Trust and Sign parvient à POSTer les données mais ne reçoit pas la réponse à cause d'un problème réseau, ces notifications en échec seront retentées et donc reçues deux fois par l'IT client.

Contenu des données de la requête web hook POST

Le POST http fait par Trust and Sign est de type Content-Type: application/x-www-form-urlencoded et le contenu de la requête contient le paramètre notifications qui est un tableau d'objets JSON, chaque objet étant une notification. Le tableau a une taille pouvant être relativement importante (jusqu'à 10 événements).

D'autres paramètres additionnels pourraient exister, ils doivent être ignorés.

Exemple de tableau notifications (contenu décodé du format URL-encoded) :

{
    "notifications": [
        {
            // Identifiant unique de la notification, et date de l'événement
            "id": 154567,
            "date": "2018-10-31T08:46:02.956Z",
            // Événement survenu (cf. liste ci-après)
            "event": "CREATION",
            // Identifiant Trust and Sign du dossier
            "clientFileUuid": "00000001-1234-5678-abcd-aaaaaaaaaaaa",
            // Optionnel: identifiant externe du dossier (si défini en création)
            "externalId": "test-extId1",
            // Optionnel (selon la configuration): liste des informations externes du dossier
            "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",
            // Optionnel: identifiant du participant si event DOCUMENT_SUBMITTED_FOR_PARTICIPANT ou ALL_MANDATORY_DOCUMENT_SUBMITTED_FOR_PARTICIPANT
            "participantUuid": "fa03c1f3-2a7c-4a2f-b041-35be3c48b9d6",
            // Optionnel: identifiant de la tâche si event 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",
            // Optionnel: identifiant du participant si event DOCUMENT_SUBMITTED_FOR_PARTICIPANT ou 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",
            // Optionnel: état du dossier si event CLIENT_FILE_CLOSED
            "clientFileState": "REJECTED",
            // Optionnel: raison du rejet si event CLIENT_FILE_CLOSED et clientFileState REJECTED
            "rejectionCause": "EXPIRED"
        },
        {
            "id": 167848,
            "date": "2025-01-30T13:22:58.991495Z",
            "event": "IDENTITY",
            "clientFileUuid": "00000002-1234-5678-abcd-aaaaaaaaaaab",
            // Optionnel: état de la requête LiveCheck si event IDENTITY (valeurs possibles DISABLED | SENT | NOT_SENT)
            "liveCheckRequest": "DISABLED",
            // Optionnel: résultat des contrôles auto si event IDENTITY (valeurs possibles OK | KO)
            "autoControls": "KO"
        }
    ]
}

Liste des événements de notification web hook

Événement Description
CREATION Ouverture / création de dossier
SIGNATURE Signature de document(s) par un participant
SIGNATURE_BY_ALL Signature de document(s) par tous les participants
SUSPENDED Suspension du dossier
FINALIZATION Finalisation du dossier par l'ensemble des participants
ACCEPTATION Acceptation de dossier
IDENTITY Une tâche d'identification vient d'être faite
LIVE_CHECK_STARTED Une demande LiveCheck a été envoyée avec succès
IDENTITY_APPROVED Les éléments d'identité fournis ont été approuvés via LiveCheck
IDENTITY_APPROVED_READY_TO_SIGN LiveCheck approuvé et l'utilisateur peut maintenant signer le fichier.
IDENTITY_APPROVED_READY_TO_ADD_DOCUMENTS LiveCheck approuvé et l'utilisateur peut maintenant soumettre ses justificatifs.
IDENTITY_REJECTED Les éléments d'identité fournis ont été rejetés via LiveCheck
IDENTIFICATION_ERROR Une tâche d'identification vient de passer en erreur (AR24, LIN, ou par API)
OTP_SENT Un code OTP vient d'être envoyé
DOCUMENT_SUBMITTED_FOR_PARTICIPANT Un justificatif a été soumis par un participant
ALL_MANDATORY_DOCUMENT_SUBMITTED_FOR_PARTICIPANT Tous les justificatifs obligatoires d’un participant ont été soumis
CLIENT_FILE_FINALIZATION Le dossier est finalisé
WAITING_TO_BE_VALIDATED Le dossier est en attente de validation
REOPEN Réouverture de dossier pour document
REOPEN_FOR_SIGNATURES Réouverture de dossier pour signature
REOPEN_FOR_DOCUMENTS_AND_SIGNATURES Réouverture de dossier pour document et signature
REJECTION_AFTER_VALIDATION Rejet après validation
EXPIRED Rejet après expiration
TECHNICAL_PROBLEM Rejet après problème technique
USER_SIGNATURE_REFUSAL Rejet après refus de signature
CANCELED Rejet après annulation
TOO_MANY_OTP_TRIES Rejet après limite OTP atteinte
DOC_SUBMISSION_ERROR Rejet après erreur de soumission de document
CLIENT_FILE_CLOSED Le dossier est clos. La donnée transmise contient alors l'attribut clientFileState avec la valeur ACCEPTED ou REJECTED. Si REJECTED, un second attribut rejectionCause indique la cause dont la liste des valeurs possibles est ici. Cette notification est une notification générique qui englobe les rejets précédents et ACCEPTATION.
UNBLOCKING Déblocage de dossier
UNBLOCKING_REOPEN Réouverture après déblocage
UNBLOCKING_REFUSAL Rejet après déblocage
SERVICE_PARTICIPANTS_RECOVERY Fin de maintenance

Remarque : Lorsque les événements IDENTITY_APPROVED_READY_TO_SIGN et IDENTITY_APPROVED_READY_TO_ADD_DOCUMENTS sont envoyés alors l'événement IDENTITY_APPROVED ne sera pas envoyé.