Attendre les documents signés

Une fois la signature effectuée, la page de consentement redirige le signataire vers votre application demandeuse, sur votre URL de redirection, en transmettant les paramètres de requête suivants :

Par défaut, la page de consentement attend que les documents signés soient produits par le Request Manager avant d’effectuer la redirection, afin que l’application demandeuse puisse les récupérer dès que la redirection se produit. Cependant, la page de consentement peut être configurée pour effectuer la redirection pendant que les documents signés sont produits de façon asynchrone en arrière-plan, obligeant alors l’application demandeuse à attendre leur disponibilité.

Dans cette situation, l’application demandeuse a la possibilité d’attendre la disponibilité des documents signés en utilisant deux techniques différentes :

• Long polling : l’application demandeuse, via l’API REST du Request Manager, interroge en boucle le statut de la demande de signature jusqu’à ce que sa valeur soit finished ou error.

• Webhook : le Request Manager notifie l’application demandeuse en envoyant une requête HTTP dès que le statut de la demande de signature passe à finished ou error.

Long polling

L’application demandeuse peut effectuer des requêtes HTTP de long polling en récupérant la demande de signature, en transmettant la dernière valeur updated connue dans le paramètre updatedAfter. L’appel restera bloquant jusqu’à ce que la demande de signature soit modifiée et que sa valeur updated change.

GET /api/requests/req_01_6V3nZjiXXcMkrtUwZy4Ljj2K?updatedAfter=1787667779656 HTTP/1.1
Authorization: ApiKey 5xVpCQPEYdncwHXwCDf5sqyfN9GPrio5

Si la dernière valeur updated de la demande de signature n’est pas connue de l’application demandeuse, un premier appel sans paramètre updatedAfter peut être effectué, et la valeur renvoyée peut être utilisée pour les appels suivants. Si une nouvelle valeur updated est renvoyée lors d’un appel, l’appel suivant doit utiliser cette nouvelle valeur pour attendre un autre changement.

Un appel HTTP de long polling peut renvoyer la même valeur updated si le statut n’a pas changé dans un délai raisonnable. Dans ce cas, l’application demandeuse doit réitérer l’appel.

Le délai d’expiration du long polling peut être ajusté via la propriété longPollingTimeout, comme décrit dans la section Guides > Opération > Configuration.

De façon générale, l’application demandeuse doit boucler sur les appels de long polling jusqu’à ce que le statut de la demande de signature soit finished ou error :

{
  "clientId" : "01",
  "created" : 1787667779656,
  "id" : "req_01_6V3nZjiXXcMkrtUwZy4Ljj2K",
  "params" : {
    "bypassViewer" : "false",
    "signerEmail" : "john.doe@my-idp.com"
  },
  "profiles" : {
    "default" : {
      "forceScrollDocument" : "false"
    }
  },
  "status" : "finished",
  "updated" : 1787667780002
}

Consultez la documentation API relative au lancement de la requête pour plus d’informations sur ce point d’entrée.

Webhooks

Les webhooks permettent à une application demandeuse d’écouter les événements émis par le Request Manager, comme un changement du statut d’une demande de signature. Voici plusieurs points à prendre en compte lors de la mise en œuvre des webhooks dans votre application demandeuse :

• Le Request Manager tentera de livrer vos webhooks plusieurs fois jusqu’à une livraison réussie, selon la propriété client webhookReattemptDelays. Pour être considérée comme réussie, votre gestionnaire de webhook doit accuser réception de la livraison en renvoyant un code de statut 2xx immédiatement après la réception de l’événement.

• Les points de terminaison webhook peuvent occasionnellement recevoir le même événement plusieurs fois. Vous devez donc vous prémunir contre les livraisons d’événements dupliquées en rendant le traitement de vos événements idempotent.

• Il n’est pas garanti que les événements soient livrés dans l’ordre dans lequel ils ont été générés.

• Les événements que vous recevez peuvent être obsolètes, voire falsifiés par un attaquant si votre point de terminaison webhook est public. Vous devez donc vérifier l’événement en effectuant un appel à l’API REST du Request Manager et en vérifiant sa cohérence avec les ressources auxquelles il se rapporte. Par exemple, lors de la réception d’un événement requestFinished, vous devez récupérer la demande de signature avec votre clé API pour vous assurer qu’elle est valide et non expirée.

• Si vous utilisez une URL HTTPS pour votre point de terminaison webhook, le Request Manager vérifiera que la connexion à votre serveur est sécurisée avant d’envoyer les données du webhook. Pour cela, votre serveur doit être correctement configuré pour prendre en charge HTTPS avec un certificat serveur valide.

Il existe différents types d’événements que les webhooks peuvent recevoir.

Les événements sont livrés à votre point de terminaison sous forme de requêtes HTTP POST, avec les champs JSON suivants dans le corps de la requête :

Par exemple, voici ce que vous recevriez comme charge utile pour un événement requestFinished :

{
  "id": "evt_whque5jODABeZq6VoOuumMFQ",
  "type": "requestFinished",
  "requestId": "req_demo_1VXf0WvwGFTfI7ZZa6gVcXTx",
  "url": "https://my-company.com/webhook",
  "attempt": 1,
  "attempted": 1559856006947
}

Pour commencer à recevoir des événements, il vous suffit d’ajouter l’URL de votre point de terminaison webhook à la propriété client webhookUrls.