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

Un groupe hôtelier veut voir chaque réservation confirmée dans son entrepôt de données, à la minute, sans export manuel. Interroger l'API toutes les cinq minutes coûte des appels et rate parfois un changement.

Un webhook inverse le sens : c'est Joinways qui appelle votre adresse HTTPS dès qu'une demande, un événement ou un devis change, avec l'enregistrement à jour et une signature à vérifier. Deux mécanismes existent : les abonnements, qui écoutent tout l'espace, et l'action « Appeler un webhook » d'une automatisation, qui part seulement quand sa règle le décide.

Ce que vous allez apprendre

• Choisir entre un abonnement et l'action d'automatisation.
• Créer un abonnement et garder son secret.
• Vérifier la signature d'un appel.
• Comprendre les reprises et la désactivation automatique.
• Voir et supprimer les webhooks de l'espace.

Prérequis

• L'offre Pro ou la période d'essai.
• Le rôle « Propriétaire » ou « Administrateur » pour créer un abonnement et voir la page « Développeurs ».
• Une adresse HTTPS publique qui répond vite. Les adresses locales, les plages privées et les noms internes sont refusés.

1. Choisir le bon mécanisme

• Abonnement : vous enregistrez une adresse une fois, et Joinways l'appelle à chaque changement du type choisi, partout dans l'espace. C'est ce qu'utilise Zapier, et ce qu'il faut pour recopier vos données ou piloter Make ou n8n.
• Action « Appeler un webhook » : une étape d'automatisation, qui part après le délai et les conditions de la règle. Par exemple, deux jours après la fin d'un mariage de plus de 100 personnes.
• Ni l'un ni l'autre : pour lire des données à la demande, utilisez une clé API et appelez l'API.

2. Créer un abonnement

Un abonnement ne se crée pas depuis un formulaire de l'app. Deux voies existent :

• Zapier : un Zap construit sur un déclencheur Joinways crée l'abonnement pour vous (voir Connecter Joinways à Zapier).
• L'API : POST /api/v1/webhooks avec une clé API, un target_url et la liste event_types.

Huit types d'événements sont disponibles :

• lead.created : une demande arrive.
• lead.archived : une demande est archivée.
• lead.merged : une demande en double est fusionnée dans une autre (champ merged_into_lead_id).
• event.created : un événement est créé.
• event.status_changed : le statut d'un événement change (previous_status, new_status).
• event.stage_changed : l'étape d'un événement change (previous_stage_id, new_stage_id, new_stage_name).
• quote.created : un devis est créé.
• quote.status_changed : le statut d'un devis change, signature comprise.

La réponse contient le secret de signature (whsec_…), une seule fois. Rangez-le tout de suite : sans lui, vous ne pouvez vérifier aucun appel. Un espace compte au plus 25 abonnements actifs.

3. Recevoir et vérifier un appel

Chaque envoi est un POST JSON : event_type, account_id, occurred_at, les champs propres au type, et data, l'enregistrement relu au moment de l'envoi, dans la forme que renvoie l'API (un élément de GET /events ou de GET /leads, ou l'objet quote de GET /quotes/{id}). Les événements sur plusieurs jours portent leurs horaires par jour dans day_hours.

Les en-têtes :

• X-Joinways-Event : le type d'événement.
• X-Joinways-Delivery : un identifiant unique, le même pour toutes les reprises d'un envoi. Dédoublonnez sur cette valeur.
• X-Joinways-Timestamp : l'heure d'envoi, en secondes Unix.
• X-Joinways-Signature-V2 : sha256= suivi d'un HMAC-SHA256 de <timestamp>.<corps brut>, calculé avec votre secret.
• X-Joinways-Signature : la première version, un HMAC-SHA256 du corps brut seul, gardée pour les récepteurs existants.

Pour vérifier, recalculez le HMAC sur le corps exactement tel que reçu, avant toute lecture JSON, comparez-le à l'en-tête, et refusez un horodatage de plus de 5 minutes pour bloquer les rejeux. Un corps reformaté par votre framework ne correspondra jamais.

Astuce : répondez 200 dès réception, puis traitez la charge en arrière-plan. Un endpoint qui travaille avant de répondre finit en échec, puis désactivé.

4. Reprises et désactivation automatique

• Un appel sans réponse au bout de 10 secondes compte comme un échec. Les redirections ne sont pas suivies.
• Chaque envoi est tenté 3 fois de suite. S'il échoue sur une erreur réseau, un délai dépassé, une erreur 5xx, 408 ou 429, il est retenté après 10 minutes, 30 minutes, 2 heures, 6 heures et 24 heures, avec le même X-Joinways-Delivery.
• Une autre réponse 4xx n'est pas retentée. Une réponse 410 supprime l'abonnement : c'est ainsi que Zapier signale un Zap coupé.
• Après 10 envois en échec d'affilée, l'abonnement passe en « Désactivé ».
• Un webhook en échec ne bloque jamais l'action dans Joinways.

5. L'action « Appeler un webhook » d'une automatisation

Dans une automatisation, l'action « Appeler un webhook » envoie l'enregistrement retenu à l'adresse indiquée, après le délai et les conditions de la règle. L'en-tête X-Joinways-Event vaut alors workflow.action, ce qui permet à un même endpoint de distinguer les deux sources.

Le secret est facultatif. S'il est renseigné, l'appel porte l'en-tête X-Joinways-Signature, calculé sur le corps brut. Une erreur réseau, 5xx, 408 ou 429 est retentée ; une autre réponse 4xx ou une redirection est consignée comme ignorée dans l'historique de l'automatisation.

6. Voir et supprimer les webhooks

Ouvrez « Réglages » > « Développeurs », onglet « Webhooks ». Le compteur de l'onglet donne le nombre total. La liste réunit tous les points de sortie de l'espace :

• les abonnements, avec la source « Zapier » ou « API », l'adresse, les événements écoutés, l'état « Actif » ou « Désactivé » et la date de création ;
• les webhooks des automatisations, avec la source « Automatisation · » suivie du nom de la règle et le lien « Modifier dans l'automatisation ».

Pour supprimer un abonnement, cliquez sur l'icône corbeille. La fenêtre « Supprimer ce webhook ? » rappelle l'adresse et les événements concernés ; la suppression est définitive. Un abonnement désactivé ne se réactive pas : recréez-le.

Exemple : les réservations d'un groupe dans son entrepôt de données

Un groupe de trois hôtels abonne un endpoint à event.status_changed et event.stage_changed. Son récepteur vérifie la signature V2, répond 200 tout de suite, puis écrit la ligne indexée sur l'identifiant de l'événement : une reprise met la ligne à jour au lieu de la dupliquer. Le jour où l'endpoint tombe, Joinways retente pendant une trentaine d'heures ; s'il reste muet dix fois de suite, l'abonnement apparaît « Désactivé » dans l'onglet « Webhooks ».

Dépannage

Rien n'arrive

Cause : l'abonnement est désactivé, ou il n'écoute pas le type que vous testez. Solution : vérifiez son état et ses événements dans l'onglet « Webhooks », et recréez-le si besoin.

La signature ne correspond jamais

Cause : l'empreinte est calculée sur un corps resérialisé, ou la V2 est calculée sans l'horodatage. Solution : capturez le corps brut avant toute lecture, et calculez la V2 sur <timestamp>.<corps brut>.

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 adresse publique ; en développement local, passez par un tunnel.

La création répond 422 quota_exceeded

Cause : l'espace a déjà 25 abonnements actifs. Solution : supprimez ceux qui ne servent plus.

J'ai perdu le secret

Cause : il ne s'affiche qu'à la création. Solution : supprimez l'abonnement et créez-en un nouveau.

Questions fréquentes

Un même changement peut-il arriver deux fois ?

Oui, après une reprise. Dédoublonnez sur X-Joinways-Delivery et rendez votre traitement idempotent.

Plusieurs adresses peuvent-elles écouter le même événement ?

Oui. Chaque abonnement actif qui écoute ce type reçoit l'envoi.

L'envoi est-il garanti ?

Il est retenté pendant environ 33 heures. Au-delà, il n'est plus rejoué : gardez l'API comme source de vérité pour une réconciliation.

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

Non. Les abonnements se créent par Zapier ou par l'API ; l'onglet « Webhooks » les liste et les supprime. L'action d'une automatisation se règle entièrement dans l'automatisation.

Voir aussi

• API REST : créer et gérer vos clés
• Connecter Joinways à Zapier
• Déclencheurs, conditions et actions : la référence
• Offres, tarifs et abonnement