Webhooks¶

Avertissement

Il est vivement recommandé de consulter un développeur, un architecte de solutions ou un autre rôle technique avant de décider d’utiliser les webhooks et tout au long du processus de mise en œuvre. S’ils ne sont pas correctement configurés, les webhooks peuvent perturber la base de données Odoo et leur rétablissement peut prendre du temps.

Les webhooks, qui peuvent être créés dans Odoo Studio, permettent d’automatiser une action dans votre base de données Odoo lorsqu’un événement spécifique se produit dans un autre système externe.

En pratique, cela fonctionne comme suit : lorsque l’événement se produit dans le système externe, un fichier de données (le « payload ») est envoyé à l’URL du webhook Odoo via une requête API POST, et une action prédéfinie est exécutée dans votre base de données Odoo.

Contrairement aux actions planifiées, qui s’exécutent à intervalles prédéfinis, ou aux requêtes API manuelles, qui doivent être explicitement invoquées, les webhooks permettent une communication et une automatisation en temps réel, pilotées par des événements. Par exemple, vous pouvez configurer un webhook pour que vos données d’inventaire Odoo soient mises à jour automatiquement lorsqu’une commande client est confirmée dans un système de point de vente externe.

Configurer un webhook dans Odoo ne nécessite aucun codage lors de la connexion de deux bases de données Odoo, mais tester un webhook nécessite un outil externe. Des enregistrements ou actions cibles personnalisés peuvent nécessiter des compétences en programmation.

Note

Cet article traite de la création d’un webhook qui reçoit des données depuis une source externe. Cependant, il est également possible de créer une action automatisée qui envoie des données vers un webhook externe lorsqu’un changement se produit dans votre base de données Odoo.

Créer un webhook dans Odoo¶

Important

Avant d’implémenter un webhook dans une base de données en production, configurez-le et testez-le en utilisant une base de données dupliquée pour vous assurer que le webhook fonctionne comme prévu.

Astuce

Activer le mode développeur avant de créer un webhook offre une plus grande flexibilité dans la sélection du modèle ciblé par la règle d’automatisation. Cela permet également de trouver le nom technique du modèle et des champs, qui peut être nécessaire pour configurer le payload.

Pour trouver le nom technique d’un modèle, avec le mode développeur activé, survoler le nom du modèle puis cliquer sur (Lien interne). Le nom technique se trouve dans le champ Modèle. Par exemple, un webhook de commande client utilise le modèle Commande client, mais le nom technique sale.order est utilisé dans le payload.

Pour créer un webhook dans Studio, procéder comme suit :

Ouvrir Studio et cliquer sur Webhooks, puis Nouveau.
Donner au webhook un nom clair et significatif qui identifie son objectif.
Si nécessaire, et à condition que le mode développeur soit activé, sélectionner le Modèle approprié dans la liste déroulante. Si le mode développeur n’est pas activé, la règle d’automatisation cible le modèle actuel par défaut.
L’URL du webhook est générée automatiquement, mais peut être modifiée si nécessaire en cliquant sur Faire pivoter le secret. Il s’agit de l’URL qui doit être utilisée lors de l’implémentation du webhook dans le système externe qui enverra des mises à jour à la base de données.

Avertissement
L’URL est confidentielle et doit être traitée avec précaution. La partager en ligne ou sans précaution peut fournir un accès involontaire à la base de données Odoo. Si l’URL est mise à jour après l’implémentation initiale, veiller à la mettre à jour dans le système externe.
Si souhaité, activer Enregistrer les appels pour suivre l’historique des requêtes API effectuées vers l’URL du webhook, par exemple à des fins de dépannage.
Si le système envoyant le webhook n’est pas Odoo, ajuster le code Enregistrement cible pour rechercher l’enregistrement JSON inclus dans la charge utile lorsque la requête API est faite à l’URL du webhook. Si le système envoyant le webhook est une base de données Odoo, s’assurer que id et model apparaissent dans la charge utile.

Si le webhook est utilisé pour créer des enregistrements dans la base de données Odoo, utiliser model.browse(i) ou model.search(i) au lieu du format Enregistrement cible par défaut.
Cliquer sur Ajouter une action dans l’onglet Actions à faire pour définir les actions à exécuter.
Avant de mettre en œuvre le webhook dans le système externe, le tester pour s’assurer qu’il fonctionne comme prévu.

Astuce

Les webhooks peuvent également être créés via le menu Automatisations dans Studio en sélectionnant le déclencheur Sur webhook.
Pour accéder à l’historique des requêtes API si Enregistrer les appels a été activé, cliquer sur le bouton intelligent Journaux en haut du formulaire Règles d’automatisation.
Si le but du webhook est autre que de mettre à jour un enregistrement existant, par exemple pour créer un nouvel enregistrement, l’action Exécuter du code doit être choisie.

Tester un webhook¶

Tester un webhook nécessite une charge utile de test et un outil ou système externe, comme Postman, pour envoyer la charge utile via une requête API POST. Cette section présente les étapes pour tester un webhook dans Postman.

Astuce

Consulter la section des cas d’usage de webhook pour des explications étape par étape sur la façon de tester les webhooks en utilisant des charges utiles de test.
Pour obtenir une aide spécifique sur le test d’un webhook avec Postman, contacter leur équipe de support.

Dans Postman, créer une nouvelle requête HTTP et définir sa méthode sur POST.
Copier l’URL du webhook depuis la base de données Odoo en utilisant l’icône (lien) et la coller dans le champ URL dans Postman.
Cliquer sur l’onglet Body et sélectionner raw.
Définir le type de fichier sur JSON, puis copier le code de la charge utile de test et le coller dans l’éditeur de code.
Cliquer sur Envoyer.

Dans le visualiseur Réponse en bas de l’écran dans Postman, les détails, y compris un code de réponse HTTP, indiquent si le webhook fonctionne correctement ou non.

Un message 200 OK ou status: ok indique que le webhook fonctionne correctement du côté d’Odoo. À partir de là, la mise en œuvre peut commencer avec l’autre système pour envoyer automatiquement les requêtes API à l’URL du webhook Odoo.
Si une autre réponse est retournée, le numéro qui lui est associé aide à identifier le problème. Par exemple, un message 500 Internal Server Error signifie qu’Odoo n’a pas pu interpréter correctement l’appel. Dans ce cas, s’assurer que les champs trouvés dans le fichier JSON sont correctement mappés dans la configuration du webhook et dans le système envoyant l’appel de test.

Astuce

Activer l’enregistrement des appels dans la configuration du webhook dans Odoo fournit des journaux d’erreurs si le webhook ne fonctionne pas comme prévu.

Implémenter un webhook dans un système externe¶

Lorsque le webhook a été créé avec succès dans Odoo et testé, l’implémenter dans le système qui envoie des données à la base de données Odoo, en s’assurant que les requêtes API POST sont envoyées à l’URL du webhook.

Cas d’usage des webhooks¶

Ci-dessous se trouvent deux exemples d’utilisation des webhooks dans Odoo. Une charge utile de test est fournie pour chaque exemple et peut être trouvée dans la section sur le test du webhook. Postman est utilisé pour envoyer la charge utile de test.

Mettre à jour la devise d’une commande client¶

Ce webhook met à jour une commande client dans l’application Ventes vers USD lorsque le système externe envoie une requête API POST à l’URL du webhook qui inclut ce numéro de commande client (identifié par l’enregistrement id de la charge utile).

Cela peut être utile pour des filiales en dehors des États-Unis avec une société mère située aux États-Unis ou lors de fusions pour consolider des données dans une seule base de données Odoo.

Créer le webhook¶

Pour créer ce webhook, procéder comme suit :

Ouvrir l’application Ventes, puis ouvrir Studio et cliquer sur Webhooks. Le modèle Commande client est sélectionné par défaut.
Cliquer sur Nouveau. Le Déclencheur est défini sur Sur webhook par défaut.
Définir l”Enregistrement cible sur model.env[payload.get('model')].browse(int(payload.get('id'))), où :
- payload.get('model') récupère la valeur associée à la clé model dans le payload, c’est-à-dire sale.order, qui est le nom technique du modèle Commande client.
- payload.get('id') récupère la valeur associée à la clé id dans le payload, c’est-à-dire le numéro de la commande client cible dans votre base de données Odoo avec le S et les zéros initiaux supprimés.
- int convertit l’id récupéré en entier (c’est-à-dire un nombre entier) car la méthode browse() ne peut être utilisée qu’avec un entier.
Cliquer sur Ajouter une action.
Dans la section Type, cliquer sur Mettre à jour l’enregistrement.
Dans la section Détails de l’action, sélectionner Mettre à jour, choisir le champ Devise, et sélectionner USD.
Cliquer sur Enregistrer & Fermer.

Tester le webhook¶

Pour tester ce webhook, procéder comme suit :

Avec Postman ouvert, créer une nouvelle requête HTTP et définir sa méthode sur POST.
Copier l’URL du webhook Odoo en utilisant l’icône (lien) et la coller dans le champ URL dans Postman.
Cliquer sur l’onglet Body et sélectionner raw.
Définir le type de fichier sur JSON, puis copier ce code, c’est-à-dire la charge utile, et le coller dans l’éditeur de code :
```
{
    "model": "sale.order",
    "id": "SALES ORDER NUMBER"
}
```
Dans votre base de données Odoo, choisir une commande client pour tester le webhook. Dans le code collé, remplacer SALES ORDER NUMBER par le numéro de la commande client sans le S ni les zéros avant le numéro. Par exemple, une commande client avec le numéro S00007 doit être saisie comme 7 dans Postman.
Cliquer sur Envoyer.
Consulter le Response viewer dans Postman pour déterminer si le webhook fonctionne correctement. Si un message autre que 200 OK ou status: ok est retourné, le numéro associé au message aide à identifier le problème.

Ajouter un contact¶

Ce webhook utilise du code personnalisé pour créer un nouveau contact dans une base de données Odoo lorsque le système externe envoie une requête API POST à l’URL du webhook qui inclut les informations du contact. Cela peut être utile pour créer automatiquement de nouveaux fournisseurs ou clients.

Créer le webhook¶

Pour créer ce webhook, procéder comme suit :

Ouvrir l’application Contacts, puis ouvrir Studio et cliquer sur Webhooks. Le modèle Contact est sélectionné par défaut.
Cliquer sur Nouveau. Le Déclencheur est défini sur Sur webhook par défaut.
Définir l”Enregistrement cible sur model.browse([2]). Il s’agit essentiellement d’un espace réservé, car le code de l’action automatisée indique au webhook ce qui doit être récupéré de la charge utile et dans quel modèle l’enregistrement doit être créé.
Cliquer sur Ajouter une action.
Dans la section Type, cliquer sur Exécuter du code.

Copier ce code et le coller dans l’éditeur de code dans l’onglet Code de la section Détails de l’action :

# variables to retrieve and hold data from the payload
contact_name = payload.get('name')
contact_email = payload.get('email')
contact_phone = payload.get('phone')

# a Python function to turn the variables into a contact in Odoo
if contact_name and contact_email:
    new_partner = env['res.partner'].create({
        'name': contact_name,
        'email': contact_email,
        'phone': contact_phone,
        'company_type':'person',
        'customer_rank': 1,
    })
# an error message for missing required data in the payload
else:
    raise ValueError("Missing required fields: 'name' and 'email'")

Cliquer sur Enregistrer & Fermer.

Tester le webhook¶

Pour tester ce webhook, procéder comme suit :

Dans Postman, créer une nouvelle requête HTTP et définir sa méthode sur POST.
Copier l’URL du webhook Odoo en utilisant l’icône (lien) et la coller dans le champ URL dans Postman.
Cliquer sur l’onglet Body et sélectionner raw.
Définir le type de fichier sur JSON, puis copier ce code, c’est-à-dire la charge utile, et le coller dans l’éditeur de code :
```
{
    "name": "CONTACT NAME",
    "email": "CONTACTEMAIL@EMAIL.COM",
    "phone": "CONTACT PHONE NUMBER"
}
```
Dans le code collé, remplacer CONTACT NAME, CONTACTEMAIL@EMAIL.COM et CONTACT PHONE NUMBER par les informations d’un nouveau contact.
Cliquer sur Envoyer.
Consulter le Response viewer dans Postman pour déterminer si le webhook fonctionne correctement. Si un message autre que 200 OK ou status: ok est retourné, le numéro associé au message aide à identifier le problème.

Modifier sur GitHub