Un webhook peut être utilisé pour notifier un événement à une autre application. Les webhooks sont généralement déclenchés par un événement, par exemple pour notifier à votre application le changement d’état d’une entité.
Il existe deux concepts pour notifier des changements à une application. L’un est le polling et l’autre est le pushing. Le polling n’est pas optimal car il n’y a normalement pas de mise à jour et le poll est gaspillé. C’est pourquoi nous utilisons des mises à jour par pushing. Les webhooks sont un concept qui permet à l’application intéressée par les mises à jour d’en être informée par une requête HTTP. En d’autres termes, l’application peut s’enregistrer pour certains événements et nous envoyons une requête HTTP lorsqu’un tel événement se produit.
Tous les détails de la configuration peuvent être définis à l’intérieur du Space > Settings > General > Webhook Listeners. Vous pouvez définir ici l’URL et choisir parmi les différents événements pour lesquels vous souhaitez recevoir un appel HTTP.
Toutes les URL auxquelles vous souhaitez qu’un webhook soit envoyé sont configurées de manière centralisée dans Space > Settings > General > Webhooks URLs. Cliquez pour ajouter une URL de webhook. La gestion centralisée des URL vous permet de gérer plus facilement les modifications apportées aux URL afin de ne pas avoir à toucher à chaque configuration de listener de webhook.
Vous pouvez également créer une URL de webhook de manière programmatique via notre API ou notre SDK : exemple ici.
Mise à jour importante sur le mécanisme de signature des webhooks:
Nous vous recommandons vivement de commencer à intégrer le nouveau mécanisme de signature dans vos webhooks dès que possible. Cela permettra d’assurer une transition en douceur lorsque la fonctionnalité deviendra obligatoire. Après la période de transition, l’ancien processus de traitement des webhooks sera progressivement supprimé.
Pourquoi avons-nous mis en place la signature du payload des webhooks ?
Dans le cadre de nos efforts constants pour respecter les normes les plus strictes en matière de sécurité et d’intégrité des données, nous avons mis en place un mécanisme robuste de signature des données utiles pour nos webhooks. Cette approche est centrée sur l’utilisation de la cryptographie à clé publique et privée, combinée à des algorithmes de hachage sécurisés, pour authentifier et vérifier les données que nous envoyons.
Voici comment ce processus renforce la sécurité et la fiabilité de nos webhooks :
Génération et gestion d’une paire de clés de chiffrement pour le webhook :
Nous générons une paire de clés cryptographiques composée d’une clé privée et d’une clé publique. La clé privée, stockée en toute sécurité
dans notre base de données, est utilisée pour signer les données utiles des webhooks.
La clé publique est partagée avec vous pour permettre la vérification de ces signatures et peut être récupérée via le keyId généré de manière unique
en utilisant le point de terminaison read dans la section
Webhook Encryption Service.
Processus de signature :
Chaque fois qu’une charge utile de webhook est envoyée, nous hachons d’abord la charge utile à l’aide de l’algorithme de hachage SHA-256,
complété par l’algorithme de signature numérique à courbe elliptique (ECDSA), afin de créer une représentation distincte et sécurisée du contenu
de la charge utile.
Ce hachage est ensuite crypté avec notre clé privée, formant ainsi une signature numérique. Cette signature numérique est essentielle pour garantir
l’intégrité et l’authenticité de la charge utile. Nous ajoutons ensuite cette signature à la requête HTTP sortante du webhook sous la forme d’un
header personnalisé nommé x-signature.
La valeur de cet en-tête comprend des détails essentiels tels que l’algorithme utilisé (SHA256withECDSA), un identifiant de clé unique (keyId),
et la signature réelle.
Cette en-tête joue un rôle essentiel en permettant au destinataire du webhook de vérifier l’authenticité des données reçues en utilisant les
informations fournies, en s’assurant que la charge utile provient bien d’une source fiable et qu’elle n’a pas été modifiée pendant le transit.
Transmission sécurisée des données utiles :
Le payload, accompagnée de sa signature numérique, vous est transmise. Ce processus garantit que les données utiles vous parviennent exactement telles que nous les avons envoyées, sans altération ni modification non autorisée.
Vérification par les clients :
Lors de la réception d’un payload de webhook, vous pouvez vérifier son authenticité et son intégrité. En hachant le payload à l’aide de la même méthode et en décryptant la signature à l’aide de la clé publique récupérée, vous pouvez confirmer que le payload est légitime et n’a pas été modifiée. Une correspondance entre le hachage calculé et la signature décryptée indique que le payload est authentique et qu’elle a bien été envoyée par notre système.
Le processus de vérification de l’authenticité et de l’intégrité du payload utile du webhook reçue est effectué de manière programmatique par l’intermédiaire de notre SDK. Lors de la réception du payload de webhook, votre application peut utiliser les méthodes SDK fournies pour valider le payload.
Exemple d’en-tête de requête de transaction:__
"x-signature" : "algorithm=SHA256withECDSA, keyId=2dcd5b38-78a1-47ea-a1c7-ed760403d88c, signature=jXt3fB8v7v/ea2MGUXj+c+FCUF6su51lCnH1DK/0tm444f6508K8FGtAFqVAmH/faJnzvE1IxLtcR6sj8M9b0g=="Un listener peut écouter les changements d’état d’entités particulières. Cela signifie que lorsqu’une entité passe à l’état spécifié, l’URL sera invoquée. Seul le certaines entités peut être souscrit par un listener de webhook. Un listener de webhook peut être créé sous Space > Settings > General > Webhook Listeners.
Vous pouvez également créer un listener de manière programmatique à l’aide de notre API ou de notre SDK : exemple ici.
Un log de tous les webhooks déclenchés peut être consulté sous Space > Connect > Webhooks > Invocations. En cliquant sur l’invocation, vous pouvez voir l’erreur en cas d’échec du webhook, y compris la réponse que nous avons reçue de votre serveur.
NOTE : Nous essayons de délivrer l’événement jusqu’à ce que nous atteignions un certain nombre de tentatives. Le délai entre les tentatives est augmenté après chaque tentative. Lorsque la livraison continue d’échouer, le listener est désactivé afin d’éviter toute invocation ultérieure d’un listener potentiellement mort.
La requête HTTP envoyée pour un changement d’état d’une entité contient les données suivantes :
eventId : Un identifiant unique qui identifie le changement d’état. Il sera toujours différent pour chaque notification.
entityId : L’ID de l’entité qui a été modifiée.
listenerEntityId : L’entité listener indique quel type d’entité a été modifié.
listenerEntityTechnicalName : Le nom technique de l’entité listener fournit un nom pour le type d’entité.
spaceId : L’identifiant de l’espace auquel appartient l’entité qui a été modifiée.
webhookListenerId : L’identifiant de l’auditeur.
timestamp : L’heure à laquelle le changement d’état s’est produit.
{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000"
}Une fois que vous avez reçu la notification sur votre URL, vous devez appeler notre API pour lire l’état de l’entité qui a changé. L’avantage principal est que nous sommes en mesure de vous notifier également sur des URL non sécurisés et que nous n’avons pas besoin d’échanger des données sensibles directement avec votre système.
|
Note
|
Nous recommandons l’utilisation de HTTP(s), c’est-à-dire une connexion cryptée, si vous avez l’intention d’utiliser la charge utile signée numériquement, expliquée ci-dessus. |
Pour lire l’état de l’entité et d’autres détails, vous devez utiliser le point de terminaison read correspondant dans le fichier
Documentation API en utilisant le entityId.
La requête HTTP qui est envoyée pour un changement d’état d’une entité inclut maintenant un champ supplémentaire state, qui fournit des informations
sur la mise à jour de l’état de l’entité surveillée. Cette amélioration est le résultat de la mise en œuvre de notre mécanisme de cryptage des webhooks.
Le champ state du payload fournit des informations directes sur la mise à jour de l’état de l’entité, ce qui rend redondants les appels supplémentaires
à l’API pour récupérer l’état de l’entité.
{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000",
"state": "PROCESSING"
}Avec l’introduction du champ state, une fois que vous avez reçu la notification à votre endpoint, la nécessité de faire des appels API supplémentaires à
notre système pour lire l’état de l’entité modifiée est considérablement réduite. Cette amélioration permet non seulement de rationaliser le processus,
mais aussi de maintenir la sécurité en minimisant l’échange de données sensibles.
Pour que les webhooks fonctionnent correctement, il est important que la configuration de votre firewall et de votre serveur permette la communication avec nos serveurs. Ce document fournit toutes les informations nécessaires pour configurer vos firewall afin de permettre le trafic entre votre infrastructure et nos services, minimisant ainsi le risque d’erreurs/de problèmes de communication.
Ce document suppose que le commerçant est familiarisé avec les procédures de configuration des firewall, des routeurs ou de tout autre dispositif utilisé pour bloquer le trafic sur le réseau du commerçant.