Configurer des webhooks

Un webhook envoie une requête HTTP à l'URL de votre choix chaque fois qu'il se passe quelque chose dans votre salon, par exemple lorsqu'un rendez-vous est créé ou qu'un client est mis à jour. Utilisez-le pour garder un autre système synchronisé avec Softalon.

Créer un webhook

1. 1

   Étape 1 sur 4

   Ouvrez Webhooks

   Allez dans Paramètres › Développeurs › Webhooks et cliquez sur Créer un webhook.

2. 2

   Étape 2 sur 4

   Saisissez la destination

   Renseignez l'URL de destination, par exemple https://example.com/webhook, et éventuellement une Description pour le reconnaître plus tard.

3. 3

   Étape 3 sur 4

   Choisissez les sujets

   Sous Sujets, sélectionnez les événements souhaités. L'onglet Tous les sujets liste tous les sujets disponibles, et Sujets sélectionnés affiche ce que vous avez choisi. Votre URL ne reçoit que les sujets que vous sélectionnez.

4. 4

   Étape 4 sur 4

   Enregistrez

   Cliquez sur Créer le webhook.

   Vous verrez:

   Webhook créé, et le webhook apparaît dans le tableau avec son interrupteur de statut activé.

Sujets

Les sujets sont nommés resource.action. Les sujets suivants sont disponibles :

Pour la signification de chaque déclencheur, consultez Les déclencheurs d'automatisation expliqués.

Ce que Softalon envoie

Chaque événement est une requête POST avec un corps JSON :

{
  "topic": "booking/appointment.created",
  "event": {
    "id": "...",
    "type": "booking/appointment.created",
    "resource": "booking/appointment",
    "resourceId": "...",
    "salonId": "...",
    "data": {
      "object": { "...": "the full object" },
      "previousAttributes": { "...": "changed fields, for updates" }
    }
  }
}

La requête comporte les en-têtes suivants :

Vérifier la signature

Chaque webhook possède un secret. Softalon signe le corps de la requête avec ce secret en HMAC-SHA256 et envoie le résultat hexadécimal dans X-Webhook-Signature. Calculez la même valeur à partir du corps brut de la requête et comparez. Si elles ne correspondent pas, ignorez la requête.

const crypto = require("crypto");

function isValid(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Pour gérer le secret, utilisez les boutons de la colonne Secret :

• Le bouton en forme d'œil affiche le secret complet, et le bouton de copie le copie.
• Le bouton de régénération crée immédiatement un nouveau secret. L'ancien secret cesse aussitôt de fonctionner : mettez donc votre système à jour en même temps.

Envois et nouvelles tentatives

• Votre URL doit répondre avec un code de statut 2xx dans les 10 secondes. Toute autre réponse compte comme un échec.
• Un envoi échoué est retenté, jusqu'à 5 tentatives au total. Les délais entre les tentatives augmentent : environ 30 secondes, 1 minute, 2 minutes et 4 minutes.
• Utilisez X-Webhook-Delivery-Id pour ignorer un envoi que vous avez déjà traité.

Chaque envoi a l'un des statuts suivants :

L'application n'affiche pas encore de journal des envois. Vous pouvez consulter les envois via l'API à l'adresse GET /v1/salons/:salonId/webhook-endpoints/:webhookEndpointId/deliveries. Consultez Créer une application API.

Modifier, suspendre ou supprimer un webhook

• Suspendre : désactivez l'interrupteur de la colonne Statut.
• Modifier : ouvrez le menu de la ligne et choisissez Mettre à jour.
• Supprimer : ouvrez le menu de la ligne et choisissez Supprimer.

Les webhooks n'envoient des données que tant que votre salon a un abonnement actif, en essai ou en retard, sur un forfait qui inclut les webhooks.