Utilisation des webhooks
Aperçu du traitement des fichiers via un flux de webhook.
Cette page suppose que vous avez de l’expérience dans la configuration d’un serveur Web dans le langage de votre choix.
Aperçu
Les webhooks permettent à Mindee de publier un résultat d’inférence directement sur votre serveur Web.
Ils offrent les temps de réponse les plus rapides et sont les plus flexibles.
C’est la méthode recommandée pour une utilisation en production, surtout en cas d’usage intensif. Les webhooks sont particulièrement adaptés au traitement d’un grand nombre de fichiers sur une courte période. Par exemple, plusieurs lots de factures à la fin du mois.
Vous devrez disposer de votre propre serveur Web et d’une URL vers laquelle Mindee peut envoyer POST des requêtes.
L’URL doit être accessible publiquement et sécurisée (TLS).
Diagramme de séquence
Remarques
Une fois qu’une requête a été envoyée, il n’est pas possible d’arrêter ou d’annuler le traitement.
Configuration de la plateforme
Un point de terminaison webhook est une configuration qui permet à Mindee d’effectuer un POST vers une URL donnée, et à vous de la spécifier lors du téléversement d’un fichier.
Les points de terminaison webhook sont configurés par modèle. Cela vous permet de configurer un point de terminaison spécifique sur votre serveur pour chaque modèle présent dans votre organisation Mindee.
Nous vous recommandons vivement d’utiliser une URL distincte pour chaque modèle, afin de faciliter la désérialisation de la charge utile d’inférence. Nous ne pourrons pas vous fournir d’assistance si vous envoyez tous les modèles à la même URL.
Création d’un point de terminaison
Dans la plateforme Mindee, accédez à votre modèle en cliquant dessus depuis la page "My Models".
Une fois sur la page du modèle, il y aura un " lien "Webhooks" dans le menu de gauche, cliquez dessus.
Sur la page Webhooks, il y aura un bouton "Add Webhook", cliquez dessus :
Cela ouvre une boîte de dialogue vous permettant de saisir le nom du webhook et l’URL de votre serveur Web.
Choisissez un nom qui vous semble pertinent.
Les URL de webhook doivent respecter les règles suivantes :
Sécurisé à l'aide de TLS (HTTPS).
Disponible publiquement en utilisant uniquement l'URL, sans authentification en-têtes.
L'authentification peut être fournie dans l'URL sous forme de paramètres de requête : nom d'utilisateur+mot de passe ou jeton
Le serveur Mindee va y aura pas suivre les redirections (HTTP 3xx).
La route doit renvoyer OK (HTTP 2xx) en cas de réussite.
Vous pouvez créer autant de points de terminaison webhook que vous le souhaitez. C’est utile par exemple si vous souhaitez envoyer vers différents environnements de votre système (c.-à-d. dev, staging, prod). Cela permet également de faciliter les tests locaux.
Une fois les informations requises saisies, le point de terminaison apparaîtra dans la liste des points de terminaison webhook.
Un bouton "Copy ID" vous permet d’utiliser réellement le webhook dans vos appels API.
Vous pouvez également utiliser le "Signing Secret" pour valider les charges utiles à l’aide de HMAC:
Suppression d’un point de terminaison
Dans votre liste de points de terminaison webhook, cliquez simplement sur l’icône de corbeille "" pour supprimer un point de terminaison.
Toute tentative future d’utiliser un webhook supprimé entraînera une erreur HTTP.
Envoyer des fichiers à l’aide des webhooks
Lors de la mise en file d’attente d’un fichier ou d’une URL, indiquez simplement les identifiants de point de terminaison webhook que vous souhaitez utiliser.
L’ID du point de terminaison est un UUID v4 et peut être obtenu en cliquant sur le bouton "Copy ID" dans votre liste de points de terminaison webhook.
Les résultats d’inférence seront envoyés à chaque point de terminaison de la liste donnée.
En général, vous n’avez besoin d’indiquer que le paramètre Webhook IDs.
Pour plus d’informations, consultez : Envoyer un fichier ou une URL.
Tests locaux
Pour tester votre intégration localement, il existe plusieurs solutions open source comme rathole, frp, ou localtunnel.
Il existe également des produits propriétaires comme ngrok.
Chargement d’une inférence
Sur votre serveur Web, vous devrez disposer d’un gestionnaire pour l’URL que vous avez configurée dans le point de terminaison webhook.
Mindee publiera les résultats d’inférence vers cette URL.
Le traitement du résultat consiste ensuite à charger la charge utile JSON envoyée depuis le serveur Web.
La charge utile est identique à un résultat obtenu par interrogation, et son traitement se fait exactement de la même manière.
Plus de détails ici : Traitement des réponses
Nous vous recommandons vivement en enregistrant tous les chargements utiles reçus sur le disque ou dans une base de données avant de tenter de charger l’inférence. Nous ne pourrons pas vous fournir d’assistance si vous n’êtes pas en mesure de récupérer les charges utiles après les avoir reçues.
Foire aux questions
Puis-je récupérer les données en cas d’erreur avec le webhook ?
Oui, sous certaines conditions.
Si votre serveur renvoie une erreur lorsque nous effectuons un POST sur le webhook, l’inférence sera disponible sur le serveur pendant un certain temps. La durée exacte de stockage des données dépend des Paramètres de stockage, mais le minimum de temps de stockage est de 1 heure.
Vous pouvez effectuer une requête GET sur l’ID de tâche pour récupérer les données tant que l’inférence est sur le serveur. L’ID de tâche est toujours renvoyé lorsqu’un document est envoyé avec succès ; il est important de conserver cet ID lorsque vous utilisez les webhooks dans ce type de scénario.
Mis à jour
Ce contenu vous a-t-il été utile ?
Comment puis-je configurer différents environnements comme les tests, la préproduction et la production ?
Vous pouvez créer autant de points de terminaison webhook que vous le souhaitez : créez-en un pour chaque environnement.
Dans votre code, ajoutez une variable d’environnement comme
MINDEE_V2_WEBHOOK_IDet définissez-la en fonction du point de terminaison correspondant.Lors de l’envoi d’un fichier pour inférence, spécifiez l’identifiant du webhook à l’aide de la variable d’environnement.