Les webhooks : pousser vos événements Joinways vers vos outils

Un webhook, c'est Joinways qui vous appelle au lieu de vous qui interrogez Joinways. Dès que quelque chose change dans votre espace, une requête HTTPS arrive sur une adresse qui vous appartient, portant l'enregistrement modifié. C'est ainsi que vous alimentez un entrepôt de données, un canal Slack à vous, un outil comptable, ou tout ce qui doit réagir sans que personne ressaisisse.

Deux mécanismes distincts portent ce nom, et savoir lequel vous concerne épargne un après-midi. Cet article couvre les deux.

Le plan qu'il vous faut

Les deux voies sont des fonctionnalités Pro. La section Développeurs et l'API qui gère les abonnements demandent le Pro, tout comme les automatisations.

Les deux sortes de webhooks

• Les abonnements : vous enregistrez une adresse une fois, et Joinways l'appelle chaque fois qu'un enregistrement concerné change, où que ce soit dans l'espace. C'est ce qu'utilise Zapier, et ce qu'il vous faut pour une intégration générale.
• L'action d'automatisation : une étape dans une règle, déclenchée seulement pour les événements que cette règle retient, après son délai et ses conditions. C'est ce qu'il vous faut quand l'appel doit porter votre propre règle métier.

Les abonnements répondent à où partent mes données ; l'action d'automatisation répond à quand exactement cela doit partir. Les deux peuvent cohabiter sur le même endpoint, et l'en-tête vous dit qui appelle.

Les abonnements

À quoi vous pouvez vous abonner

Quatre types d'événements, et c'est la liste complète :

• lead.created, quand une nouvelle demande arrive dans l'Inbox.
• event.created, quand un événement est créé.
• event.status_changed, quand un événement passe entre En option, Confirmé, Perdu ou Annulé.
• quote.status_changed, quand un devis change d'état, signature comprise.

Un abonnement peut en écouter plusieurs. Les événements arrivent dans la même forme que celle renvoyée par l'API sur GET /api/v1/events : le même code de lecture fonctionne des deux côtés.

En créer un

Deux moyens, et aucun n'est un formulaire dans l'app.

• Via Zapier : construisez un Zap sur un déclencheur Joinways et l'abonnement est créé pour vous.
• En appelant vous-même POST /api/v1/webhooks, avec votre adresse de destination et les types d'événements voulus.

L'adresse doit être en HTTPS public. Les adresses locales, les plages privées et les noms internes sont refusés : un test en local demande donc un tunnel avec une vraie adresse publique.

La création renvoie un secret de signature, une fois et une seule. Conservez-le tout de suite : Joinways ne le réaffiche jamais, et sans lui vous ne pouvez vérifier aucun appel.

Les voir et les supprimer

Paramètres puis Développeurs liste tous les abonnements de l'espace, avec leur adresse, les événements écoutés, leur état actif ou désactivé, et leur date de création. En supprimer un arrête les envois immédiatement et ne se défait pas.

Vérifier un appel

Chaque envoi porte un en-tête X-Joinways-Signature, de la forme sha256 suivi d'une empreinte hexadécimale. Cette empreinte est un HMAC-SHA256 du corps brut de la requête, calculé avec votre secret.

Pour la contrôler, calculez le même HMAC sur le corps exactement tel que reçu, avant toute lecture ou reformulation JSON, et comparez les deux. Un corps que votre framework a resérialisé ne correspondra pas : c'est la cause la plus fréquente d'une vérification qui échoue sur un appel parfaitement valide.

Refusez tout ce qui ne correspond pas, et traitez le secret comme un identifiant : qui le détient peut forger un appel qui ressemble aux nôtres.

Envoi, reprises et désactivation automatique

• Chaque envoi est tenté jusqu'à trois fois, avec une courte pause entre les tentatives.
• Un appel sans réponse au bout de dix secondes est considéré comme échoué. Répondez vite en 2xx, et travaillez ensuite.
• Après dix échecs consécutifs, un abonnement est désactivé automatiquement, plutôt que de marteler indéfiniment une adresse morte.
• Un webhook en échec ne bloque jamais l'action dans Joinways. Une réservation se confirme même si votre endpoint est tombé.

💡 Répondez 200 dès que vous avez la charge, puis traitez-la en arrière-plan. Les endpoints qui travaillent avant de répondre sont ceux qui finissent désactivés.

L'action d'automatisation

Dans une automatisation, Appeler un webhook envoie l'événement retenu à l'adresse que vous indiquez, après le délai et les conditions de la règle. L'appel porte un en-tête qui le désigne comme venant d'une action d'automatisation : un endpoint qui reçoit aussi des abonnements peut donc les distinguer.

Le secret de signature est optionnel ici : laissez-le vide pour un envoi non signé, ou renseignez-en un et obtenez le même en-tête de signature qu'un abonnement. La même règle du HTTPS public s'applique.

Les échecs se comportent autrement que pour les abonnements : une erreur réseau ou une erreur serveur de votre côté est retentée, un refus comme une mauvaise adresse est consigné comme ignoré et n'est pas retenté, un endpoint mal configuré ne se corrigeant pas tout seul.

Lequel choisir

• Recopier vos données quelque part, ou piloter Zapier, Make ou n8n : un abonnement.
• Appeler quelque chose deux jours après la fin d'un événement, seulement pour les mariages de plus de 100 personnes : l'action d'automatisation, où vivent le délai et les conditions.
• Lire des données à la demande plutôt que les recevoir : ni l'un ni l'autre. Utilisez une clé API et appelez l'API.

Bonnes pratiques

• Vérifiez la signature à chaque appel, sans exception. Un endpoint non vérifié est un canal d'écriture public vers vos systèmes.
• Rendez votre traitement idempotent : une reprise peut livrer deux fois le même changement, et cela ne doit pas créer deux lignes.
• Ne vous abonnez qu'à ce que vous utilisez. Moins de types d'événements, c'est moins d'appels et un journal plus lisible.
• Vérifiez la liste Développeurs après une mise en production chez vous : un abonnement désactivé en silence est la raison classique d'un flux qui s'arrête.

Résolution de problèmes

Rien n'arrive

Cause : l'abonnement a été désactivé après des échecs répétés, ou il n'écoute pas le type d'événement que vous testez. Solution : ouvrez Paramètres puis Développeurs, vérifiez son état et ses événements, et recréez-le si besoin.

La signature ne correspond jamais

Cause : vous calculez l'empreinte sur un corps resérialisé plutôt que sur le corps brut. Solution : capturez le corps tel que reçu, avant toute lecture, et calculez dessus.

L'adresse est refusée à la création

Cause : elle n'est pas en HTTPS public, ou elle pointe vers un hôte privé ou interne. Solution : exposez une vraie adresse publique, avec un tunnel pour le développement local.

J'ai perdu le secret

Cause : il ne s'affiche qu'une fois, à la création. Solution : supprimez l'abonnement et créez-en un nouveau, qui vous donne un secret neuf.

Exemple concret

Un groupe veut chaque réservation confirmée dans sa propre base de reporting à la minute. Il abonne un endpoint à event.status_changed, vérifie la signature, et écrit la ligne indexée sur l'identifiant de l'événement pour qu'une reprise mette à jour au lieu de dupliquer. Plus personne n'exporte à la main, et un endpoint muet dix fois de suite apparaît désactivé dans Développeurs plutôt que sous forme de données manquantes en silence.

Questions fréquentes

Puis-je créer un webhook depuis l'app ?

Les abonnements se créent via Zapier ou l'API ; la page Développeurs les liste et les supprime. L'action webhook d'une automatisation, elle, se configure entièrement dans le constructeur.

Quels événements existent ?

Quatre : une demande créée, un événement créé, un statut d'événement changé, un statut de devis changé.

L'envoi est-il garanti ?

Il est tenté trois fois. Au-delà, le changement n'est pas rejoué : considérez l'API comme votre source de vérité pour une réconciliation.

Plusieurs endpoints peuvent-ils écouter le même événement ?

Oui. Chaque abonnement actif correspondant au type d'événement le reçoit.

Un webhook en échec casse-t-il quelque chose dans Joinways ?

Non. L'envoi se fait en dehors de l'action : rien dans l'app n'attend votre endpoint.

À lire aussi

• Les clés API
• Déclencheurs, conditions et actions : la référence
• Plans et tarifs