➜︎ Retour - Menu API, webhooks et mailhooks

Webhooks et mailhooks : fonctionnement

Menu de la documentation

API

Démarrer Rechercher un client Lister les clients Créer un client Modifier un client La fiche client en JSON Les erreurs OpenAPI et Postman

Webhooks et mailhooks

Fonctionnement Vente : validation Article : stock mis à jour Les webhooks Client

Cette page explique comment Melkal envoie ses webhooks et ses mailhooks automatiques. Ils se règlent dans le menu
Réglages → API & Make.

Un webhook ou un mailhook automatique, c'est Melkal qui envoie de lui-même les informations d'un événement (une vente validée, du stock mis à jour...) à votre application : Make, Zapier, votre logiciel de gestion, votre site... Votre application n'a pas besoin d'interroger Melkal pour savoir ce qui s'est passé.

Cette page décrit les envois « Vente : validation » et « Article : stock mis à jour ». Les webhooks « Client » (création, modification de la fiche...) partent directement, en une seule tentative, sans file d'attente ni relance : voir Les webhooks Client.

Webhook ou mailhook ?#

	Webhook	Mailhook
Destination	Une adresse web, qui commence par https://	Une adresse email
Ce qui part	Une requête HTTP POST dont le corps est le JSON	Un email dont le corps est le même JSON, en texte
Accusé de réception	Votre application répond (code 200 à 204) : Melkal sait que c'est bien reçu	Le service d'envoi d'emails de Melkal a accepté le message. Melkal ne sait pas si votre robot l'a ensuite traité
À choisir pour	Les services qui reçoivent des appels web : Make, Zapier, une application à vous...	Les services qui se pilotent par email plutôt que par une adresse web

Le contenu envoyé est exactement le même dans les deux cas : ce sont les pages Vente : validation et Article : stock mis à jour qui le détaillent.

Les activer#

Ouvrez Réglages → API & Make, vue Webhooks ou Mailhooks.
Sur la ligne de l'événement, saisissez l'URL (webhook) ou l'adresse email (mailhook). Pour désactiver, videz la case.
Vérifiez que l'interrupteur Webhooks activés est sur Oui, dans Clé et adresse de l'API. Il commande à la fois les webhooks et les mailhooks automatiques.

Quand les données partent#

Au moment de l'événement, Melkal inscrit simplement l'envoi dans une file d'attente, dans la même opération que la vente ou le mouvement de stock. Votre application ne peut donc jamais ralentir ni bloquer une vente. Un traitement séparé vide ensuite cette file : l'envoi part en général dans la minute qui suit, parfois jusqu'à deux minutes.

Le contenu est préparé au moment de l'envoi : il reflète l'état de Melkal à cet instant, par exemple le stock d'un article.

Ce que reçoit votre application (webhook)#

Élément	Explications
Méthode	POST
Corps	Le JSON, en UTF-8.
En-têtes	Content-Type: application/json cleApi : la clé saisie dans la colonne « Clé » du webhook, ou « Melkal » si vous n'en avez pas saisi. Servez-vous-en pour vérifier que la requête vient bien de Melkal. User-Agent: Melkal/8
Réponse attendue	Un code HTTP 200 à 204, en moins de 30 secondes (15 secondes pour établir la connexion). Toute autre réponse est un échec : une erreur 4xx ou 5xx, une redirection (301, 302...) que Melkal ne suit pas, ou une absence de réponse.

Conseil : répondez 200 tout de suite, puis traitez les données. Votre application n'a pas à renvoyer de contenu.

Si votre application ne répond pas#

Melkal réessaie, avec des attentes de plus en plus longues. Un webhook qui échoue ne retarde pas les autres.

Après l'échec n°	Attente avant la tentative suivante
1	1 minute
2	5 minutes
3	30 minutes
4	2 heures
5	6 heures
6	12 heures
7	Plus de nouvelle tentative : l'envoi est abandonné.

Ces délais sont des minimums : le traitement passe une fois par minute.

Doublons et ordre des envois#

Un même événement peut arriver plus d'une fois, et dans le désordre après une panne. Il faut en tenir compte côté application.

Melkal garantit qu'un événement est envoyé au moins une fois. Si le serveur est arrêté entre l'envoi et l'enregistrement de son résultat, l'envoi est refait. Chaque envoi porte un idEvenement : il est le même à chaque nouvelle tentative. Gardez les identifiants déjà traités pour ignorer les doublons.
Après une panne, un événement ancien peut arriver après un événement plus récent. Ne comptez pas sur l'ordre de réception : servez-vous des numéros et des dates contenus dans le JSON.
Une relance contient l'état de Melkal au moment de la relance, pas celui de l'événement d'origine. Pour le stock, la valeur reçue (stockFinal) est donc toujours le stock réel du moment de l'envoi.

Conventions du JSON#

Donnée	Format
Montants	Des chaînes de caractères, en euros, avec un point et deux décimales : "12.50". Les montants négatifs commencent par un tiret : "-1.60" (une annulation, un rendu de monnaie). Passez-les en nombre décimal dans votre application.
Taux, pourcentages	Des chaînes avec deux décimales : "20.00" pour une TVA à 20 %.
Quantités vendues	Des chaînes avec le nombre de décimales de l'unité de l'article : "2" pour des articles à l'unité, "1.250" pour un article vendu au kilo.
Quantités et stocks de l'événement « stock »	Des nombres entiers (le stock n'est géré que pour des articles à l'unité).
Dates et heures	Du texte au format "AAAA-MM-JJ HH:MM:SS", à l'heure locale de votre entreprise, sans fuseau horaire (ce n'est pas de l'ISO 8601 : un espace sépare la date et l'heure). Certaines dates (fin de validité d'une carte de fidélité) n'ont pas d'heure.
Types	Les pastilles de type de la documentation sont celles du JSON : string, integer, boolean, array et object.
Identifiants	Des nombres entiers : ceux de Melkal. Une valeur 0 veut dire « aucun ».
Oui / Non	Les booléens JSON true et false.
Texte vide	"" : la propriété est présente mais sans valeur.
Propriété absente	Quelques propriétés n'existent que dans certains cas. La documentation de chaque propriété le dit : « absente si... ». Testez toujours leur présence avant de les lire.
Listes	Des tableaux JSON, qui peuvent être vides : [].
Ajouts futurs	Melkal peut ajouter des propriétés à un JSON. Ignorez celles que vous ne connaissez pas, au lieu de refuser le message.

Le mailhook#

Élément	Explications
Destinataire	L'adresse saisie dans la colonne « Email » du mailhook.
Objet de l'email	Ce que vous avez saisi dans la colonne « Objet / clé » (par défaut « Envoi Mailhook Melkal »). Vous pouvez y mettre une clé, pour vérifier à la réception que l'email vient bien de Melkal.
Corps de l'email	Le JSON, en texte brut.
Expéditeur	L'adresse email de votre entreprise, si vous avez branché votre propre compte Mailjet dans Melkal (modules externes). Sinon contact@melkal.ovh.
Relances	Les mêmes que pour un webhook : Melkal réessaie quand le service d'envoi d'emails n'a pas accepté le message.

Tester#

Pour voir ce que Melkal envoie sans écrire de programme, saisissez dans la colonne « URL » l'adresse fournie par un service de test comme webhook.site, ou l'adresse d'un module « Custom webhook » de Make. Provoquez ensuite l'événement (validez une vente, une entrée de stock...) : l'envoi arrive dans la minute.

← PrécédentOpenAPI et Postman Suivant →Vente : validation

Dernière mise à jour : 13 octobre 2026

Retour - Sommaire - Centre d'aide - Assistance