Pour télécharger l'exemple complet de code, consultez notre site Partage de code.

Les notifications d'événements par rappel vous permettent d'être automatiquement informé des événements qui concernent un paquet (dans la New User Experience, les paquets sont appelés « transactions »). Lorsqu'un événement spécifique se produit, le système envoie automatiquement un message à une destination que vous avez choisie.

Emplacement dans l'interface utilisateur

Tout d'abord, vous devez localiser cette zone dans votre IU. Après avoir exécuté votre code, vous pourrez vérifier ici qu'il s'est bien exécuté. Pour trouver la zone de rappel à partir de l'interface utilisateur, connectez-vous à OneSpan Sign et cliquez sur Admin > Notification d'événement.

Capture

Comme vous le verrez, cette zone est complètement vide (sauf si vous l'avez déjà configurée).

Notifications disponibles

Avant de passer au code, il serait bon de connaître toutes les notifications disponibles. Comme vous pouvez le voir dans l'image ci-dessus, il y en a plusieurs. Le tableau suivant les répertorie comme ils doivent être représentés, dans votre code :

Dans le tableau suivant :

  • La taille maximale de tous les champs sessionUser est de 255 caractères.
  • La taille maximale de tous les champs packageId est de 255 caractères.
  • Le champ sessionUser dépend du fait que l'événement a été généré ou non par un expéditeur ou un signataire. Les événements déclenchés par l'expéditeur auront l'ID de l'expéditeur. Les événements déclenchés par le signataire auront l'ID du signataire.
Événement Signification Données utiles JSON
DOCUMENT_SIGNED Un document a été signé, ou des accords de consentement et/ou de divulgation ont été acceptés.

{ "name": "DOCUMENT_SIGNED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

DOCUMENT_VIEWED Un document a été visualisé.

{ "name": "DOCUMENT_VIEWED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

EMAIL_BOUNCE

Un courriel a rebondi. Les types de rebond sont les suivants :

  • « BOUNCE » (un rebond dur)
  • « COMPLAINT » (un rebond doux)
  • « OOTO » (absence du bureau)
  • « UNKNOWN »

Pour obtenir plus d'informations, consultez notre liste de modèles.

{ "name": "EMAIL_BOUNCE",

"sessionUser": "...",

"packageId": "......",

"message": "bounce type",

"createdDate": "2017-05-02T20:17:58.408Z" }

KBA_FAILURE Il y a eu un échec KBA Authentication.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ACTIVATE Un paquet a été déplacé du statut ÉBAUCHE ou SUPPRIMÉ au statut ENVOYÉ. Par défaut, un paquet est créé dans le statut ÉBAUCHE, et est déplacé vers le statut ENVOYÉ lorsqu'il est prêt à être traité par les signataires.

{ "name": "PACKAGE_ACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ARCHIVE Une notification de rappel indique qu'un paquet a été archivé.

{ "name": "PACKAGE_ARCHIVE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ATTACHMENT Une notification de rappel indique qu'un signataire a téléversé une pièce jointe.

{ "name": "PACKAGE_ATTACHMENT",

"sessionUser": "...",

"packageId": "......",

"message": "attachment name", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_COMPLETE

Un paquet a terminé le processus de signature.

S'il y a plusieurs signataires, le "sessionUser": "...", sera l'ID du dernier signataire à avoir signé.

{ "name": 'PACKAGE_COMPLETE',

"sessionUser": '...',

"packageId": '......',

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_CREATE Un paquet a été créé. Ainsi, le système d'origine peut enregistrer l'ID du paquet OneSpan Sign.com, ainsi que l'ID de la transaction du système d'origine.

{ "name": "PACKAGE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DEACTIVATE Le statut d'un paquet est passé de ENVOYÉ à ÉBAUCHE.

{ "name": "PACKAGE_DEACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DECLINE Si un destinataire a refusé de signer un paquet et qu'il en a donné le motif, le système d'origine peut utiliser cette raison pour déterminer l'étape suivante pour le paquet.

{ "name": "PACKAGE_DECLINE",

"sessionUser": "...",

"packageId": "......",

"message": "decline reason", (max 4000 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DELETE Un paquet a été supprimé du système OneSpan Sign.com.

{ "name": "PACKAGE_DELETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_EXPIRE Un paquet a dépassé sa date d'expiration.

{ "name": "PACKAGE_EXPIRE",

"sessionUser": "...",

"packageId": "...",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_READY_FOR_COMPLETE Un paquet a été marqué comme DO_NOT_AUTOCOMPLETE. Une action de l'expéditeur sera nécessaire pour compléter le paquet.

{ "name": "PACKAGE_READY_FOR_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_RESTORE Un paquet a été mis à la corbeille, mais il est en train de revenir à le statut dans lequel il se trouvait avant d'être mis à la corbeille.

{ "name": "PACKAGE_RESTORE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_TRASH Un paquet a été déplacé dans la corbeille de la Inbox de OneSpan Sign (statut = SUPPRIMÉ).

{ "name": "PACKAGE_TRASH",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

ROLE_REASSIGN Un signataire a délégué sa signature à un autre signataire.

{ "name": "ROLE_REASSIGN",

"sessionUser": "...",

"packageId": "......",

"newRoleId": "......", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_COMPLETE Un signataire a terminé de signer tous les documents.

{ "name": "SIGNER_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_LOCKED Une notification de rappel indique qu'un signataire a été verrouillé en raison d'échecs répétés d'authentification par Message texte/Q&R.

{ "name": "SIGNER_LOCKED",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

TEMPLATE_CREATE Une notification par rappel indique qu'un modèle a été créé.

{ "name": "TEMPLATE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

Réception des notifications d'événements

Une fois que vous vous êtes inscrit pour être informé d'un ou de plusieurs types d'événements, il vous suffit d'écouter les notifications associées. Lorsqu'un événement pertinent est déclenché, OneSpan Sign envoie un HTTP POST à votre URL enregistrée. Ce message contient des données utiles au format JSON, décrivant l'événement qui a déclenché la notification.

La clé de rappel que vous avez enregistrée est transmise dans l'en-tête d'autorisation sous la forme « {callbackKey} ». Vous l'utiliserez pour vous assurer que vous recevez des notifications qui contiennent le secret partagé, de sorte que vous sachiez que vous ne recevez pas de faux appels et que vous pouvez réagir en conséquence.

Vous trouverez ci-dessous quelques exemples de données utiles de rappel :

Package was Created
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_CREATE","sessionUser":"18EZDL44xgsX","packageId":"wVdZEaPD2igwUnFGJBjDD0dpO7k=","message":null,"documentId":null,"createdDate":"2018-06-30T20:04:55.384Z"}
Package was Sent
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_ACTIVATE","sessionUser":"18EZDL44xgsX","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:09:50.425Z"}
Signer 1 accepted consent document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"default-consent","createdDate":"2018-06-30T20:10:51.002Z"}
Signer 1 completed a document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691","createdDate":"2018-06-30T20:12:12.256Z"}
Signer 1 completed signing package
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"SIGNER_COMPLETE","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:12:12.272Z"}
Package was Complete
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_COMPLETE","sessionUser":"e00696ec-d6f5-4feb-89c5-a5ce002a6c66","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:15:01.038Z"}

Configuration des notifications de rappel

Les exemples de code suivants peuvent être utilisés pour définir l'URL de rappel, la clé de rappel et vous abonner à trois notifications d'événements différents.

  1. Créez votre EslClient avec votre API_KEY et API_URL (n'oubliez pas d'utiliser des applications au lieu de votre Sandbox pour les environnements de production). Veillez à changer les valeurs API_KEY, API_URL, URL et KEY avec vos propres valeurs.
    final String API_KEY = "YOUR_API_KEY";
    final String API_URL = "https://sandbox.esignlive.com/api";
    final String URL = "http://my.url.com";
    final String KEY = "myCallbackKey";
    EslClient eslClient = new EslClient( API_KEY, API_URL );
  2. Faites appel à votre EventNotificationService pour vous enregistrer pour les notifications PACKAGE_CREATE, PACKAGE_DECLINE, et PACKAGE_COMPLETE. Vous pouvez également ajouter d'autres abonnements de notification à partir du tableau des options, ci-dessus.
  3. eslClient.getEventNotificationService().register(newEventNotificationConfig(URL)
                    .withKey(KEY)
                    .forEvent(NotificationEvent.PACKAGE_CREATE)
                    .forEvent(NotificationEvent.PACKAGE_DECLINE)
                    .forEvent(NotificationEvent.PACKAGE_COMPLETE));

Le résultat

Après avoir exécuté votre code, voici le résultat que vous obtiendrez si vous retournez dans la zone de notification des événements de l'interface utilisateur, comme indiqué dans la section Avant de commencer.

Capture

Pour télécharger l'exemple complet de code, consultez notre site Partage de code.

Les notifications d'événements par rappel vous permettent d'être automatiquement informé des événements qui concernent un paquet (dans la New User Experience, les paquets sont appelés « transactions »). Lorsqu'un événement spécifique se produit, le système envoie automatiquement un message à une destination que vous avez choisie.

Emplacement dans l'interface utilisateur

Tout d'abord, vous devez localiser cette zone dans votre IU. Après avoir exécuté votre code, vous pourrez vérifier ici qu'il s'est bien exécuté. Pour trouver la zone de rappel à partir de l'interface utilisateur, connectez-vous à OneSpan Sign et cliquez sur Admin > Notification d'événement.

Capture

Comme vous le verrez, cette zone est complètement vide (sauf si vous l'avez déjà configurée).

Notifications disponibles

Avant de passer au code, il serait bon de connaître toutes les notifications disponibles. Comme vous pouvez le voir dans l'image ci-dessus, il y en a plusieurs. Le tableau suivant les répertorie comme ils doivent être représentés, dans votre code :

Dans le tableau suivant :

  • La taille maximale de tous les champs sessionUser est de 255 caractères.
  • La taille maximale de tous les champs packageId est de 255 caractères.
  • Le champ sessionUser dépend du fait que l'événement a été généré ou non par un expéditeur ou un signataire. Les événements déclenchés par l'expéditeur auront l'ID de l'expéditeur. Les événements déclenchés par le signataire auront l'ID du signataire.
Événement Signification Données utiles JSON
DOCUMENT_SIGNED Un document a été signé, ou des accords de consentement et/ou de divulgation ont été acceptés.

{ "name": "DOCUMENT_SIGNED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

DOCUMENT_VIEWED Un document a été visualisé.

{ "name": "DOCUMENT_VIEWED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

EMAIL_BOUNCE

Un courriel a rebondi. Les types de rebond sont les suivants :

  • « BOUNCE » (un rebond dur)
  • « COMPLAINT » (un rebond doux)
  • « OOTO » (absence du bureau)
  • « UNKNOWN »

Pour obtenir plus d'informations, consultez notre liste de modèles.

{ "name": "EMAIL_BOUNCE",

"sessionUser": "...",

"packageId": "......",

"message": "bounce type",

"createdDate": "2017-05-02T20:17:58.408Z" }

KBA_FAILURE Il y a eu un échec KBA Authentication.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ACTIVATE Un paquet a été déplacé du statut ÉBAUCHE ou SUPPRIMÉ au statut ENVOYÉ. Par défaut, un paquet est créé dans le statut ÉBAUCHE, et est déplacé vers le statut ENVOYÉ lorsqu'il est prêt à être traité par les signataires.

{ "name": "PACKAGE_ACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ARCHIVE Une notification de rappel indique qu'un paquet a été archivé.

{ "name": "PACKAGE_ARCHIVE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ATTACHMENT Une notification de rappel indique qu'un signataire a téléversé une pièce jointe.

{ "name": "PACKAGE_ATTACHMENT",

"sessionUser": "...",

"packageId": "......",

"message": "attachment name", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_COMPLETE

Un paquet a terminé le processus de signature.

S'il y a plusieurs signataires, le "sessionUser": "...", sera l'ID du dernier signataire à avoir signé.

{ "name": 'PACKAGE_COMPLETE',

"sessionUser": '...',

"packageId": '......',

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_CREATE Un paquet a été créé. Ainsi, le système d'origine peut enregistrer l'ID du paquet OneSpan Sign.com, ainsi que l'ID de la transaction du système d'origine.

{ "name": "PACKAGE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DEACTIVATE Le statut d'un paquet est passé de ENVOYÉ à ÉBAUCHE.

{ "name": "PACKAGE_DEACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DECLINE Si un destinataire a refusé de signer un paquet et qu'il en a donné le motif, le système d'origine peut utiliser cette raison pour déterminer l'étape suivante pour le paquet.

{ "name": "PACKAGE_DECLINE",

"sessionUser": "...",

"packageId": "......",

"message": "decline reason", (max 4000 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DELETE Un paquet a été supprimé du système OneSpan Sign.com.

{ "name": "PACKAGE_DELETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_EXPIRE Un paquet a dépassé sa date d'expiration.

{ "name": "PACKAGE_EXPIRE",

"sessionUser": "...",

"packageId": "...",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_READY_FOR_COMPLETE Un paquet a été marqué comme DO_NOT_AUTOCOMPLETE. Une action de l'expéditeur sera nécessaire pour compléter le paquet.

{ "name": "PACKAGE_READY_FOR_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_RESTORE Un paquet a été mis à la corbeille, mais il est en train de revenir à le statut dans lequel il se trouvait avant d'être mis à la corbeille.

{ "name": "PACKAGE_RESTORE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_TRASH Un paquet a été déplacé dans la corbeille de la Inbox de OneSpan Sign (statut = SUPPRIMÉ).

{ "name": "PACKAGE_TRASH",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

ROLE_REASSIGN Un signataire a délégué sa signature à un autre signataire.

{ "name": "ROLE_REASSIGN",

"sessionUser": "...",

"packageId": "......",

"newRoleId": "......", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_COMPLETE Un signataire a terminé de signer tous les documents.

{ "name": "SIGNER_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_LOCKED Une notification de rappel indique qu'un signataire a été verrouillé en raison d'échecs répétés d'authentification par Message texte/Q&R.

{ "name": "SIGNER_LOCKED",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

TEMPLATE_CREATE Une notification par rappel indique qu'un modèle a été créé.

{ "name": "TEMPLATE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

Réception des notifications d'événements

Une fois que vous vous êtes inscrit pour être informé d'un ou de plusieurs types d'événements, il vous suffit d'écouter les notifications associées. Lorsqu'un événement pertinent est déclenché, OneSpan Sign envoie un HTTP POST à votre URL enregistrée. Ce message contient des données utiles au format JSON, décrivant l'événement qui a déclenché la notification.

La clé de rappel que vous avez enregistrée est transmise dans l'en-tête d'autorisation sous la forme « {callbackKey} ». Vous l'utiliserez pour vous assurer que vous recevez des notifications qui contiennent le secret partagé, de sorte que vous sachiez que vous ne recevez pas de faux appels et que vous pouvez réagir en conséquence.

Vous trouverez ci-dessous quelques exemples de données utiles de rappel :

Package was Created
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_CREATE","sessionUser":"18EZDL44xgsX","packageId":"wVdZEaPD2igwUnFGJBjDD0dpO7k=","message":null,"documentId":null,"createdDate":"2018-06-30T20:04:55.384Z"}
Package was Sent
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_ACTIVATE","sessionUser":"18EZDL44xgsX","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:09:50.425Z"}
Signer 1 accepted consent document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"default-consent","createdDate":"2018-06-30T20:10:51.002Z"}
Signer 1 completed a document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691","createdDate":"2018-06-30T20:12:12.256Z"}
Signer 1 completed signing package
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"SIGNER_COMPLETE","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:12:12.272Z"}
Package was Complete
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_COMPLETE","sessionUser":"e00696ec-d6f5-4feb-89c5-a5ce002a6c66","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:15:01.038Z"}

Configuration des notifications de rappel

Les exemples de code suivants peuvent être utilisés pour définir l'URL de rappel, la clé de rappel et vous abonner à trois notifications d'événements différents.

  1. Créez votre EslClient avec votre API_KEY et API_URL (n'oubliez pas d'utiliser des applications au lieu de votre Sandbox pour les environnements de production). Veillez à changer les valeurs API_KEY, API_URL, URL et KEY avec vos propres valeurs.
    final String API_KEY = "YOUR_API_KEY";
    final String API_URL = "https://sandbox.esignlive.com/api";
    final String URL = "http://my.url.com";
    final String KEY = "myCallbackKey";
    EslClient eslClient = new EslClient( API_KEY, API_URL );
  2. Faites appel à votre EventNotificationService pour vous enregistrer pour les notifications PACKAGE_CREATE, PACKAGE_DECLINE, et PACKAGE_COMPLETE. Vous pouvez également ajouter d'autres abonnements de notification à partir du tableau des options, ci-dessus.
  3. eslClient.getEventNotificationService().register(newEventNotificationConfig(URL)
                    .withKey(KEY)
                    .forEvent(NotificationEvent.PACKAGE_CREATE)
                    .forEvent(NotificationEvent.PACKAGE_DECLINE)
                    .forEvent(NotificationEvent.PACKAGE_COMPLETE));

Le résultat

Après avoir exécuté votre code, voici le résultat que vous obtiendrez si vous retournez dans la zone de notification des événements de l'interface utilisateur, comme indiqué dans la section Avant de commencer.

Capture

Pour télécharger l'exemple complet de code, consultez notre site Partage de code.

Les notifications d'événements par rappel vous permettent d'être automatiquement informé des événements qui concernent un paquet (dans la New User Experience, les paquets sont appelés « transactions »). Lorsqu'un événement spécifique se produit, le système envoie automatiquement un message à une destination que vous avez choisie.

Emplacement dans l'interface utilisateur

Tout d'abord, vous devez localiser cette zone dans votre IU. Après avoir exécuté votre code, vous pourrez vérifier ici qu'il s'est bien exécuté. Pour trouver la zone de rappel à partir de l'interface utilisateur, connectez-vous à OneSpan Sign et cliquez sur Admin > Notification d'événement.

Capture

Comme vous le verrez, cette zone est complètement vide (sauf si vous l'avez déjà configurée).

Notifications disponibles

Avant de passer au code, il serait bon de connaître toutes les notifications disponibles. Comme vous pouvez le voir dans l'image ci-dessus, il y en a plusieurs. Le tableau suivant les répertorie comme ils doivent être représentés, dans votre code :

Dans le tableau suivant :

  • La taille maximale de tous les champs sessionUser est de 255 caractères.
  • La taille maximale de tous les champs packageId est de 255 caractères.
  • Le champ sessionUser dépend du fait que l'événement a été généré ou non par un expéditeur ou un signataire. Les événements déclenchés par l'expéditeur auront l'ID de l'expéditeur. Les événements déclenchés par le signataire auront l'ID du signataire.
Événement Signification Données utiles JSON
DOCUMENT_SIGNED Un document a été signé, ou des accords de consentement et/ou de divulgation ont été acceptés.

{ "name": "DOCUMENT_SIGNED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

DOCUMENT_VIEWED Un document a été visualisé.

{ "name": "DOCUMENT_VIEWED",

"sessionUser": "...",

"packageId": "......",

"documentId": "......", (max 256 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

EMAIL_BOUNCE

Un courriel a rebondi. Les types de rebond sont les suivants :

  • « BOUNCE » (un rebond dur)
  • « COMPLAINT » (un rebond doux)
  • « OOTO » (absence du bureau)
  • « UNKNOWN »

Pour obtenir plus d'informations, consultez notre liste de modèles.

{ "name": "EMAIL_BOUNCE",

"sessionUser": "...",

"packageId": "......",

"message": "bounce type",

"createdDate": "2017-05-02T20:17:58.408Z" }

KBA_FAILURE Il y a eu un échec KBA Authentication.

{ "name": "KBA_FAILURE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ACTIVATE Un paquet a été déplacé du statut ÉBAUCHE ou SUPPRIMÉ au statut ENVOYÉ. Par défaut, un paquet est créé dans le statut ÉBAUCHE, et est déplacé vers le statut ENVOYÉ lorsqu'il est prêt à être traité par les signataires.

{ "name": "PACKAGE_ACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ARCHIVE Une notification de rappel indique qu'un paquet a été archivé.

{ "name": "PACKAGE_ARCHIVE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_ATTACHMENT Une notification de rappel indique qu'un signataire a téléversé une pièce jointe.

{ "name": "PACKAGE_ATTACHMENT",

"sessionUser": "...",

"packageId": "......",

"message": "attachment name", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_COMPLETE

Un paquet a terminé le processus de signature.

S'il y a plusieurs signataires, le "sessionUser": "...", sera l'ID du dernier signataire à avoir signé.

{ "name": 'PACKAGE_COMPLETE',

"sessionUser": '...',

"packageId": '......',

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_CREATE Un paquet a été créé. Ainsi, le système d'origine peut enregistrer l'ID du paquet OneSpan Sign.com, ainsi que l'ID de la transaction du système d'origine.

{ "name": "PACKAGE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DEACTIVATE Le statut d'un paquet est passé de ENVOYÉ à ÉBAUCHE.

{ "name": "PACKAGE_DEACTIVATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DECLINE Si un destinataire a refusé de signer un paquet et qu'il en a donné le motif, le système d'origine peut utiliser cette raison pour déterminer l'étape suivante pour le paquet.

{ "name": "PACKAGE_DECLINE",

"sessionUser": "...",

"packageId": "......",

"message": "decline reason", (max 4000 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_DELETE Un paquet a été supprimé du système OneSpan Sign.com.

{ "name": "PACKAGE_DELETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_EXPIRE Un paquet a dépassé sa date d'expiration.

{ "name": "PACKAGE_EXPIRE",

"sessionUser": "...",

"packageId": "...",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_READY_FOR_COMPLETE Un paquet a été marqué comme DO_NOT_AUTOCOMPLETE. Une action de l'expéditeur sera nécessaire pour compléter le paquet.

{ "name": "PACKAGE_READY_FOR_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_RESTORE Un paquet a été mis à la corbeille, mais il est en train de revenir à le statut dans lequel il se trouvait avant d'être mis à la corbeille.

{ "name": "PACKAGE_RESTORE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

PACKAGE_TRASH Un paquet a été déplacé dans la corbeille de la Inbox de OneSpan Sign (statut = SUPPRIMÉ).

{ "name": "PACKAGE_TRASH",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

ROLE_REASSIGN Un signataire a délégué sa signature à un autre signataire.

{ "name": "ROLE_REASSIGN",

"sessionUser": "...",

"packageId": "......",

"newRoleId": "......", (max 255 chars)

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_COMPLETE Un signataire a terminé de signer tous les documents.

{ "name": "SIGNER_COMPLETE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

SIGNER_LOCKED Une notification de rappel indique qu'un signataire a été verrouillé en raison d'échecs répétés d'authentification par Message texte/Q&R.

{ "name": "SIGNER_LOCKED",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

TEMPLATE_CREATE Une notification par rappel indique qu'un modèle a été créé.

{ "name": "TEMPLATE_CREATE",

"sessionUser": "...",

"packageId": "......",

"createdDate": "2017-05-02T20:17:58.408Z" }

Réception des notifications d'événements

Une fois que vous vous êtes inscrit pour être informé d'un ou de plusieurs types d'événements, il vous suffit d'écouter les notifications associées. Lorsqu'un événement pertinent est déclenché, OneSpan Sign envoie un HTTP POST à votre URL enregistrée. Ce message contient des données utiles au format JSON, décrivant l'événement qui a déclenché la notification.

La clé de rappel que vous avez enregistrée est transmise dans l'en-tête d'autorisation sous la forme « {callbackKey} ». Vous l'utiliserez pour vous assurer que vous recevez des notifications qui contiennent le secret partagé, de sorte que vous sachiez que vous ne recevez pas de faux appels et que vous pouvez réagir en conséquence.

Vous trouverez ci-dessous quelques exemples de données utiles de rappel :

Package was Created
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_CREATE","sessionUser":"18EZDL44xgsX","packageId":"wVdZEaPD2igwUnFGJBjDD0dpO7k=","message":null,"documentId":null,"createdDate":"2018-06-30T20:04:55.384Z"}
Package was Sent
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_ACTIVATE","sessionUser":"18EZDL44xgsX","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:09:50.425Z"}
Signer 1 accepted consent document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"default-consent","createdDate":"2018-06-30T20:10:51.002Z"}
Signer 1 completed a document
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"DOCUMENT_SIGNED","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":"7caf46cdd75f7a411bf8c22793b84fa79d8d180becc40691","createdDate":"2018-06-30T20:12:12.256Z"}
Signer 1 completed signing package
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"SIGNER_COMPLETE","sessionUser":"44aafb7c-97b9-40e1-bb59-eb76c7d2a484","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:12:12.272Z"}
Package was Complete
{"@class":"com.silanis.esl.packages.event.ESLProcessEvent","name":"PACKAGE_COMPLETE","sessionUser":"e00696ec-d6f5-4feb-89c5-a5ce002a6c66","packageId":"5n4obeO8jYoPp126Cm-Y3fxdfbo=","message":null,"documentId":null,"createdDate":"2018-06-30T20:15:01.038Z"}

Configuration des notifications de rappel

Les exemples de code suivants peuvent être utilisés pour définir l'URL de rappel, la clé de rappel et vous abonner à trois notifications d'événements différents.

Requête HTTP

POST /api/callback

En-têtes HTTP

 Accept: application/json   Content-Type: application/json   Authorization: Basic api_key 

Données utiles de la demande

 {   "url": "https://www.esl.com/callbackNotifications",   "key": "secureKey#1",   "events": [   "PACKAGE_CREATE",   "PACKAGE_DECLINE",   "PACKAGE_COMPLETE"   ]   } 

Pour une description complète de chaque champ, voir le tableau des données utiles de la demande ci-dessous.

Données utiles de la réponse

 {   "url": "https://www.esl.com/callbackNotifications",   "key": "secureKey#1",   "events": [   "PACKAGE_CREATE",   "PACKAGE_DECLINE",   "PACKAGE_COMPLETE"   ]   } 

Le résultat

Après avoir exécuté votre code, voici le résultat que vous obtiendrez si vous retournez dans la zone de notification des événements de l'interface utilisateur, comme indiqué dans la section Avant de commencer.

Capture

Tableau des données utiles de la demande

PropriétéTypeModifiableRequisPar défautExemples de valeurs
urlchaîne de caractèresOuiNons.o.https://www.esl.com/callbackNotifications
cléchaîne de caractèresOuiNons.o.clésécurisée#1