Documentation - Notifications HTTP

Fonctionnement

À la création d'un objet Signature, ou du compte client, une ou plusieurs URLs de notification HTTP peuvent être fournies. Lorsque le signataire signe le ou les documents associés, l'API SigTool effectuera une réquête HTTP sur toutes ces URLs. Ces requêtes sont de type POST, les données identifiant l'objet Signature sont transmises en utilisant le format application/x-www-form-urlencoded, et une somme de contrôle HMAC est ajoutée afin de s'assurer que la notification provient bien de SigTool.

Données transmises

• sgt_client
  Identifiant du compte client. Cet identifiant vous est fourni à la création du compte, et permet de sélectionner la bonne clé d'API si vous en possédez plusieurs.
• sgt_curdate
  Date de la notification au format ISO8601. Permet de vérifier que la requête n'est pas rejouée dans le cadre d'une attaque. L'horloge du serveur SigTool est synchronisée régulièrement et cette date ne devrait pas différer de plus de quelques secondes de celle de votre serveur.
• sgt_token
  Valeur unique identifiant l'objet Signature, retournée à la création de ce dernier.
• sgt_signdate
  Date au format ISO8601 à laquelle le ou les documents ont été signés.
• sgt_signmethod
  Méthode utilisée pour signer le ou les documents. Peut être email, sms, touch ou mouse.
• sgt_data
  Encodage JSON de la valeur opaque clientData si fournie à l'API lors de la création de l'objet Signature. Permet de stocker des informations identifiant ces documents sur vos systèmes.
• sgt_uniqueid
  Propriété signature.unique-identifier si fournie à l'API lors de la création de l'objet Signature.
• sgt_hmac
  Somme de contrôle HMAC des paramètres ci-dessus, qui, combinée à la clé d'API du compte client, permet la vérification de l'origine de la requête, la clé d'API n'étant connue que de vous et de SigTool.

Notification SigTool

POST https://erp.client.org/sigtool/document-signed
Content-Type: application/x-www-form-urlencoded

sgt_client=identifiantclient&sgt_curdate=2024-12-23T20%3A13%3A43%2B01%3A00&sgt_data=%7B%22customerId%22%3A123456%7D&sgt_signdate=2024-12-23T20%3A13%3A40%2B01%3A00&sgt_signmethod=email&sgt_token=rKQ9qljTcXdynOzxBCnzfi3cWuqNDQl0&sgt_hmac=ec46a2906188e24021dfd7afea934365590cc08b

Réponse

En réponse à la requête de notification, votre système doit retourner un contenu texte ayant uniquement la chaîne de caractère OK sur sa première ligne. Si une deuxième ligne est fournie, celle-ci sera utilisée en interne par SigTool en tant que statut succès de la notification. Dans tous les autres cas, la notification sera re-exécutée pendant environ 7 jours par intervalle croissant, jusqu'à avoir une réponse OK, ou échouera et sera abandonnée.

200 OK
Content-Type: text/plain

OK

Vérification du HMAC

La somme de contrôle HMAC est la valeur de hachage d'un buffer créé avec les paramètres précédents, et haché via la méthode HMAC en utilisant l'algorithme SHA-1 et la clé d'API en tant que clé de hachage.

Le buffer est une chaîne de caractères UTF-8 composée de la concaténation des paramètres ci-dessus (sauf sgt_hmac), triés par nom de paramètre, suivis du caractère =, suivis de la valeur brute du paramètre, et joints entre eux par le caractère ASCII <RS> (valeur hexadécimale 1e).

sgt_client=identifiantclient <RS> sgt_curdate=2024-12-23T20:13:43+01:00 <RS> ... <RS> sgt_token=rKQ9qljTcXdynOzxBCnzfi3cWuqNDQl0

La plupart des languages de programmation proposent une fonction permettant le calcul des hash HMAC.

$params = $_POST;
$hmac = $params['sgt_hmac'];
unset($params['sgt_hmac']);

ksort($params);
$buffer = implode("\x1e", array_map(function($k, $v) {
	return "$k=$v";
}, array_keys($params), $params));
	
$valid = hash_hmac('sha1', $buffer, $api_key) == $hmac;