Aller au contenu

Galaxie Artibox

Webhooks signés : vérifier la signature d'un webhook

Soyez prévenu à chaque rendez-vous pris, déplacé ou annulé, et vérifiez la signature d'un webhook avant de le traiter.

Un webhook évite d'interroger l'API en boucle : Artibox Calendar envoie une requête POST à votre adresse dès qu'un événement se produit. Savoir vérifier la signature d'un webhook est indispensable : c'est la seule preuve que l'envoi vient bien d'Artibox Calendar et qu'il n'a pas été modifié en chemin.

Les webhooks sont inclus dès la formule Équipe (tarifs). Leur réglage dans l'application est décrit dans l'aide webhooks ; cette page en donne le détail technique.

Créer un abonnement

Depuis Réglages › Intégrations, ou par l'API avec la portée webhooks:ecrire :

curl -X POST "$RDV_API/webhook-subscriptions" \
  -H "x-api-key: $RDV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/artibox","events":["reservation.creee","reservation.annulee"]}'

La réponse contient le secret de signature whsec_…, donné une seule fois : gardez-le dans votre coffre de secrets. Un type_id facultatif limite l'abonnement aux événements d'un type. L'adresse doit être en https et ne peut pas viser un réseau interne.

Les événements

  • reservation.creee, reservation.deplacee, reservation.annulee, reservation.constatee : la vie d'un rendez-vous.
  • sondage.vote, sondage.confirme : un invité vote, une date est confirmée.
  • envoi_lien.envoye, envoi_lien.reservation_obtenue : un lien envoyé, puis la réservation qui en vient.
  • type.cree, type.modifie : un type de rendez-vous change.
  • connexion_agenda.a_reconnecter : un agenda connecté doit être reconnecté.
  • routage.soumis : un formulaire d'orientation est rempli.
  • test : envoyé par « Envoyer un test » ou POST /webhook-subscriptions/{id}/test.

Le contenu exact de chaque événement, avec un exemple, est dans la référence des événements.

Le contenu envoyé

Chaque envoi a la même enveloppe, en JSON :

{
  "id": "0192f0f5-8a9b-7c0d-9e1f-203142536475",
  "evenement": "reservation.creee",
  "cree_le": "2026-12-01T09:00:00+00:00",
  "organisation_id": "0192f0a0-0000-7000-8000-0000000000aa",
  "donnees": {
    "reservation": {
      "id": "0192f0d1-1b2c-7d3e-8f40-a1b2c3d4e5f6",
      "statut": "confirmed",
      "debut": "2026-12-01T10:00:00+01:00",
      "fin": "2026-12-01T10:30:00+01:00",
      "invite": { "nom": "Camille Martin", "email": "camille.martin@example.com", "telephone": null },
      "contexte": { "source": "mon-crm", "type": "affaire", "id": "AFF-2026-0042" },
      "liens": { "gerer": "https://…/g/…" }
    }
  }
}

Le rendez-vous envoyé comprend aussi le type, les réponses aux questions, le lien de visio, le lieu, les organisateurs, les paramètres de suivi (utm_*, gclid, fbclid, ref), l'origine et le motif d'annulation. L'id de l'enveloppe est le même pour tous les abonnements et pour chaque réessai : servez-vous-en pour ignorer un doublon.

Vérifier la signature d'un webhook

L'en-tête X-Signature a la forme t=1764579600,v1=5d41… : t est l'instant de l'envoi en secondes Unix, v1 le HMAC-SHA256, en hexadécimal, de la chaîne « t + . + corps brut », calculé avec votre secret whsec_… (la chaîne entière). Trois règles :

  1. Calculez la signature sur le corps brut, tel que reçu, avant tout décodage JSON.
  2. Comparez en temps constant.
  3. Refusez un t trop ancien (cinq minutes, par exemple) pour qu'un envoi capturé ne puisse pas être rejoué.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.RDV_WEBHOOK_SECRET; // whsec_…

app.post("/webhooks/artibox", express.raw({ type: "application/json" }), (req, res) => {
  const fields = Object.fromEntries((req.get("X-Signature") ?? "").split(",").map((part) => part.split("=", 2)));
  const age = Math.abs(Date.now() / 1000 - Number(fields.t));
  const expected = crypto.createHmac("sha256", secret).update(`${fields.t}.${req.body}`).digest("hex");
  const valid = typeof fields.v1 === "string" && fields.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(fields.v1), Buffer.from(expected));
  if (!valid || !(age <= 300)) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString("utf8"));
  console.log(event.evenement, event.id);
  res.sendStatus(204);
});

PHP

<?php
$secret = getenv('RDV_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SIGNATURE'] ?? ''), $fields);
$timestamp = (int) ($fields['t'] ?? 0);
$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (!hash_equals($expected, (string) ($fields['v1'] ?? '')) || abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
http_response_code(204);

Python (Flask)

import hashlib, hmac, json, os, time
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["RDV_WEBHOOK_SECRET"].encode()  # whsec_…

@app.post("/webhooks/artibox")
def artibox():
    fields = dict(part.split("=", 1) for part in request.headers.get("X-Signature", "").split(",") if "=" in part)
    body = request.get_data()
    expected = hmac.new(SECRET, fields.get("t", "").encode() + b"." + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, fields.get("v1", "")) or abs(time.time() - int(fields.get("t", "0"))) > 300:
        return "", 400
    event = json.loads(body)
    return "", 204

Réessais et désactivation

Répondez par un code 2xx en moins de 10 secondes, puis traitez l'événement en arrière-plan. Toute autre réponse, une redirection ou un silence compte comme un échec : l'envoi est réessayé après 1, 5, 30, 120 puis 720 minutes. Après 20 échecs de suite, l'abonnement est désactivé et les propriétaires sont prévenus ; le réactiver remet le compteur à zéro.

Le journal garde 30 jours de livraisons (GET /webhook-subscriptions/{id}/deliveries) et une livraison se rejoue avec POST /webhook-deliveries/{id}/replay. Les routes sont dans la référence des webhooks.

Bonnes pratiques

  • Rendez votre traitement idempotent : le même id peut arriver deux fois (réessai, rejeu).
  • Ne vous fiez pas à l'ordre d'arrivée : comparez cree_le et relisez le rendez-vous par l'API si besoin.
  • Une application OAuth n'entend que ce que son membre peut voir : voir intégrer dans votre plateforme.

Questions fréquentes

J'ai perdu le secret de signature, que faire ?

Il n'est jamais réaffiché. Supprimez l'abonnement et créez-en un nouveau, qui recevra un nouveau secret.

Pourquoi ma vérification échoue alors que le secret est bon ?

Le plus souvent, le corps a été décodé puis réencodé avant le calcul. Calculez le HMAC sur les octets reçus, sans les transformer, et utilisez le secret entier, préfixe whsec_ compris.

Puis-je recevoir les événements d'un seul type de rendez-vous ?

Oui : indiquez son type_id à la création de l'abonnement.

Mon adresse de webhook peut-elle être en http ?

Non. L'adresse doit être publique et en https ; les adresses du réseau interne sont refusées.

Branchez vos outils en temps réel

Créez votre premier abonnement depuis Réglages › Intégrations, puis envoyez un test.

Créer mon compte