Configurer un webhook

Pourquoi c'est utile

Votre comptable, votre transporteur ou votre propre logiciel ont besoin d'être prévenus quand une commande arrive ou qu'un paiement est enregistré. Plutôt que d'exporter des fichiers, un webhook envoie automatiquement chaque événement choisi à l'adresse de votre choix, au moment où il se produit.

Résumé

Un webhook est une adresse web (URL) que Genuka appelle à chaque événement auquel vous l'abonnez : « Commande créée », « Paiement créé », « Client mis à jour »… Il se gère dans Paramètres › Intégrations › Webhooks. Côté réception, il faut un outil capable de recevoir ces appels : un service développé par votre prestataire, ou un outil d'automatisation comme n8n.

Prérequis

• Permissions : webhooks.view pour consulter, webhooks.create, webhooks.update, webhooks.delete et webhooks.test pour le reste. La carte Webhooks des paramètres s'affiche avec webhooks.*.
• Une adresse publique en https prête à recevoir des requêtes.

Étapes

1. Ouvrez Paramètres › Intégrations › Webhooks, puis Créer un webhook.
2. Renseignez l'URL du Webhook et, si vous le souhaitez, une Description. Laissez Actif coché.
3. Dans Événements à surveiller, cochez les événements voulus. Rechercher des événements... filtre la liste, Tout sélectionner coche tout. Au moins un événement est obligatoire.
4. Enregistrez. La page du webhook s'ouvre.
5. Copiez le secret du webhook (champ « Webhook Secret », bouton de copie) et donnez-le à la personne qui configure la réception : il sert à vérifier que les appels viennent bien de Genuka.
6. Cliquez sur Tester le webhook : Genuka envoie un événement de test à votre adresse.

Champs & options

Ce que reçoit votre adresse

Chaque appel est une requête POST en JSON qui contient : le nom de l'événement (par exemple order.created), l'identifiant de votre entreprise, le type d'objet, les données de l'objet, la date et la version de l'API (2023-11). L'en-tête Signature contient une signature HMAC-SHA256 du contenu, calculée avec le secret du webhook : votre outil la recalcule et refuse tout appel dont la signature ne correspond pas.

Genuka attend la réponse 3 secondes. En cas d'échec, il réessaie jusqu'à 3 fois, en espaçant les tentatives.

Cas limites & erreurs fréquentes

• L'appel de test ne ressemble pas aux autres. L'événement de test (test) porte un message et l'identifiant du webhook, mais pas de données d'objet.
• Mon serveur répond lentement. Au-delà de 3 secondes, l'appel compte comme échoué et sera réessayé : répondez tout de suite, puis traitez l'événement de votre côté.
• Le compteur « Échecs » reste à zéro alors que mon serveur était en panne. Ce compteur ne relève que les envois que Genuka n'a pas réussi à préparer. Une adresse qui ne répond pas est réessayée 3 fois puis abandonnée, sans apparaître dans ce compteur ; le webhook n'est donc pas désactivé automatiquement dans ce cas. Surveillez la réception de votre côté.
• Après « Régénérer le Secret », plus rien n'est accepté. Mettez le nouveau secret dans votre outil de réception.
• Deux événements identiques, un seul appel. Genuka n'envoie pas deux fois exactement les mêmes données au même webhook.
• Les messages WhatsApp reçus ne font pas partie des événements. Pour réagir à un message, utilisez une automatisation avec un déclencheur WhatsApp.

FAQ

Faut-il être développeur ? Pour créer le webhook dans Genuka, non. Pour recevoir et exploiter les appels, il faut un outil prévu pour cela (développement sur mesure, ou outil d'automatisation).

Webhook ou automatisation ? Une automatisation agit dans Genuka (message, mise à jour). Un webhook prévient un autre logiciel. Une automatisation peut aussi appeler une adresse externe avec l'étape Appeler un service web.

Puis-je voir les webhooks supprimés ? Oui, avec le filtre Afficher les webhooks supprimés de la liste.

Voir aussi

• Créer une automatisation (workflow)
• Générer et gérer des clés API
• Installer une application