Webhooks

Les webhooks permettent à des systèmes extérieurs à PrimeCal de déclencher automatiquement vos règles d'automatisation. Lorsqu'un service externe — une plateforme de réservation, un CRM, une boutique en ligne — envoie un message JSON à l'URL webhook de votre règle, PrimeCal le reçoit et exécute la règle.

Comment fonctionnent les webhooks

Chaque règle d'automatisation utilisant le déclencheur webhook.incoming reçoit sa propre URL unique. Lorsqu'un système tiers envoie une requête HTTP POST signée avec un corps JSON à cette URL, votre règle se déclenche.

Le déroulement est le suivant :

1. Le système externe envoie une requête POST à votre URL webhook
2. PrimeCal reçoit la charge utile et la journalise
3. Les conditions de la règle sont évaluées par rapport aux données de la charge utile
4. Si les conditions correspondent (ou s'il n'y en a aucune), l'action s'exécute

Trouver votre URL webhook

1. Allez dans Tableau de bord → Automatisation
2. Ouvrez la règle que vous voulez connecter (ou créez-en une nouvelle avec webhook.incoming comme déclencheur)
3. Dans la vue détaillée de la règle, ouvrez l'onglet Webhook
4. Copiez l'URL — elle ressemble à :

   https://api.primecal.eu/api/automation/webhook/abc123xyz

Chaque règle a un jeton différent dans l'URL. Ce jeton identifie votre règle, mais à lui seul, il ne suffit pas à la déclencher — voir ci-dessous.

Les requêtes doivent être signées — un simple POST échouera

Contrairement à de nombreux récepteurs de webhooks simples, PrimeCal exige que chaque requête entrante porte une signature HMAC-SHA256 valide, pas seulement le jeton de l'URL. Une requête sans signature est rejetée. Cela demande plus de configuration qu'un simple POST, mais cela signifie que la fuite du jeton seul ne suffit pas à déclencher votre règle.

Envoyer une requête webhook

Votre système externe doit envoyer une requête avec Content-Type: application/json et deux en-têtes requis : un horodatage et une signature calculée à partir de votre charge utile et d'un secret propre à la règle.

Exemple de charge utile :

{
  "event": "order.completed",
  "data": {
    "order_id": "12345",
    "customer": "John Doe",
    "total": 99.99,
    "status": "paid"
  }
}

PrimeCal accepte toute structure JSON valide. La forme de premier niveau est flexible — vous pouvez utiliser data, payload, body, ou toute imbrication que vous préférez. Ce qui compte, c'est de référencer les mêmes chemins dans vos conditions en notation pointée (ex. webhook.data.order_id).

Obtenir votre secret de signature

L'application web n'affiche pas actuellement directement le secret de signature de votre règle. Récupérez-le (ou faites-le tourner) en étant connecté, en appelant :

curl -X POST https://api.primecal.eu/api/automation/rules/YOUR_RULE_ID/webhook/rotate-secret \
  -H "Authorization: Bearer YOUR_JWT_OR_API_KEY"

Cela renvoie un webhookSecret — enregistrez-le en lieu sûr, car il n'existe aucun moyen de le revoir sans le faire tourner (ce qui invalide l'ancien après une courte période de grâce). La plupart des intégrateurs font cela une fois, puis codent en dur le secret dans le système émetteur.

Calculer la signature

Pour chaque requête :

1. timestamp = l'heure Unix actuelle en secondes.
2. Construisez la chaîne "{timestamp}.{rawJsonBody}".
3. signature = HMAC-SHA256(webhookSecret, cette chaîne), en hexadécimal.
4. Envoyez X-PrimeCal-Timestamp: {timestamp} et X-PrimeCal-Signature: {signature}.

L'horodatage doit être à moins de 5 minutes de l'horloge de PrimeCal, et chaque requête signée ne peut être utilisée qu'une seule fois — cela empêche de rejouer plus tard d'anciennes requêtes interceptées.

Des exemples complets de requête/réponse (Node.js et curl) figurent dans la référence de l'API Webhook — c'est la page à transmettre à la personne qui implémente le côté émetteur.

Tester avec curl

En raison de la signature requise, les tests nécessitent le secret et une signature calculée, pas seulement un simple POST. Le moyen le plus rapide de tester est de générer la signature à la volée :

SECRET="le webhookSecret obtenu depuis rotate-secret"
BODY='{"event":"test","data":{"priority":"high","customer_id":"123"}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST https://api.primecal.eu/api/automation/webhook/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -H "X-PrimeCal-Timestamp: $TS" \
  -H "X-PrimeCal-Signature: $SIG" \
  -d "$BODY"

Remplacez YOUR_TOKEN par le jeton de l'onglet Webhook de votre règle. Après l'envoi, consultez l'onglet History de la règle dans PrimeCal pour confirmer que la requête a été reçue et journalisée.

Utiliser les données de la charge utile dans les conditions

Une fois qu'un webhook arrive, vous pouvez inspecter son contenu dans les conditions à l'aide de webhook.data avec la notation pointée :

• webhook.data.order_id → le champ order_id sous data
• webhook.data.customer → le champ customer sous data
• webhook.data.status → le champ status sous data

Exemple de règle : agir uniquement quand status est égal à "paid" :

• Champ de condition : webhook.data.status
• Opérateur : equals
• Valeur : paid

Voir Smart Values pour une explication complète de la notation pointée et de l'accès imbriqué.

Exemple pratique : confirmation de réservation

Une plateforme de réservation envoie un webhook à PrimeCal lorsque quelqu'un réserve une séance de piscine. La charge utile ressemble à ceci :

{
  "event": "booking.confirmed",
  "data": {
    "booking_id": "bk_001",
    "guest_name": "Sarah Connor",
    "slot": "2026-07-15T10:00:00",
    "type": "pool"
  }
}

Vous voulez colorer en cyan toutes les réservations de piscine entrantes pour qu'elles ressortent dans le calendrier.

Configuration de la règle :

1. Déclencheur : webhook.incoming
2. Condition : webhook.data.type égal à pool
3. Action : Définir la couleur de l'événement → Cyan

Lorsque le système de réservation déclenche le webhook, PrimeCal le reçoit, vérifie que type est pool, et applique la couleur cyan à l'événement associé.

Régénérer le jeton d'URL vs faire tourner le secret de signature

Ce sont deux valeurs différentes, et PrimeCal propose deux opérations distinctes pour cela :

• Le jeton d'URL (la partie dans l'URL du webhook) — régénérez-le depuis l'onglet Webhook de la règle si vous soupçonnez que l'URL elle-même a fuité. L'ancienne URL cesse de fonctionner immédiatement.
• Le secret de signature — faites-le tourner via l'API (voir ci-dessus) si vous soupçonnez que le secret a fuité, ou périodiquement par précaution. L'ancien secret continue de fonctionner pendant une courte période de grâce afin que vous puissiez mettre à jour le système émetteur sans interruption, puis il s'arrête.

Régénérer l'un n'affecte pas l'autre — faites tourner celui qui a réellement été exposé.

Consulter les journaux de webhooks

Chaque requête webhook — qu'elle ait déclenché l'action ou ait été filtrée par les conditions — est journalisée dans la piste d'audit de la règle.

1. Ouvrez la vue détaillée de la règle
2. Allez dans l'onglet History
3. Chaque entrée affiche l'horodatage, la charge utile entrante, les conditions évaluées, et le résultat

C'est le premier endroit à vérifier si un webhook ne semble pas fonctionner.

Dépannage

Si votre webhook ne déclenche pas la règle comme prévu, consultez Dépannage des automatisations pour une liste de vérification complète. Les problèmes les plus courants sont :

• 401 Unauthorized — en-têtes X-PrimeCal-Signature/X-PrimeCal-Timestamp manquants ou invalides, un horodatage décalé de plus de 5 minutes, ou une signature calculée avec le mauvais secret ou le mauvais corps brut. Cela n'atteint jamais l'onglet History, car la requête est rejetée avant l'exécution de la règle — vérifiez les propres journaux de votre système émetteur pour la réponse HTTP.
• En-tête Content-Type incorrect (doit être application/json)
• Le jeton dans l'URL ne correspond pas au jeton actuel de la règle
• Une condition filtre la requête (consultez l'onglet History pour connaître la raison — une réponse 200 signifie que la requête a été acceptée et évaluée, pas qu'elle correspondait)