Cowlendar Help Center

Si ton activité repose sur les réservations, tu as sans doute besoin que tes données de réservation vivent à plusieurs endroits. Ton CRM doit savoir quand un nouveau client réserve. Ton ERP a besoin des données de revenu. Ton outil marketing doit déclencher un e-mail de bienvenue. Et ton app personnalisée peut avoir besoin de créer des réservations de façon programmatique.

L’API publique et les webhooks de Cowlendar rendent tout cela possible. L’API te permet de lire tes services et tes réservations, et de créer de nouvelles réservations depuis n’importe quel système externe. Les webhooks envoient des notifications en temps réel à ton serveur chaque fois qu’il se passe quelque chose: une réservation est créée, confirmée, annulée, reprogrammée, ou un événement d’abonnement se produit.

Ces deux fonctionnalités sont actuellement en Beta.

ℹ️Info

La référence API interactive complète, avec tous les schémas et les exemples de réponse, se trouve sur https://app.cowlendar.com/public-api/docs

Que peux-tu construire avec l’API de Cowlendar?

Voici des cas d’intégration réels que les marchands Cowlendar mettent déjà en place:

Synchroniser chaque réservation avec HubSpot, Salesforce ou n’importe quel CRM. Quand un client réserve une coupe, un cours de yoga ou une location, un webhook part immédiatement avec toutes les données de réservation: nom, e-mail, téléphone, service, date, prix, membre d’équipe. Ton CRM crée ou met à jour le contact automatiquement, sans saisie manuelle.

Créer ta propre page de réservation ou ton app mobile. Utilise l’API pour récupérer tes services, y compris les durées, les membres d’équipe, les équipements et les catégories de participants, puis créer des réservations depuis ton propre frontend. La réservation déclenche les mêmes e-mails de confirmation, notifications SMS et synchronisations Google Calendar qu’une réservation effectuée via le widget Cowlendar.

Automatiser des workflows avec Zapier ou Make sans code. Pointe un webhook Cowlendar vers l’URL de webhook fournie par Zapier ou Make. Chaque événement de réservation devient un déclencheur. Envoie une notification Slack quand quelqu’un réserve, ajoute une ligne dans Google Sheets, crée une carte Trello ou lance une séquence e-mail dans Klaviyo ou Mailchimp.

Envoyer les données de réservation dans ton outil de reporting ou de BI. Utilise l’endpoint List Bookings pour récupérer toutes les réservations sur une plage de dates, filtrées par statut, service, présence ou e-mail client. Exporte ensuite ces données vers ton data warehouse, Google Sheets ou Airtable pour créer des tableaux de bord sur mesure.

Lier les réservations aux crédits d’abonnement. Quand tu crées une réservation via l’API, tu peux passer un subscription_id pour déduire automatiquement un crédit du plan du client, par exemple un pass yoga de 10 cours.

Connecter les réservations POS ou admin à des systèmes externes. Les webhooks se déclenchent pour toutes les sources de réservation: le widget storefront, le panneau admin, le POS et l’API elle-même. Rien ne tombe entre les mailles du filet.

Authentification

Chaque requête API nécessite un Bearer token généré depuis ton admin Cowlendar. Les tokens ont un accès complet en lecture et en écriture aux réservations et aux services de ta boutique. Traite-les comme des mots de passe: ne les commit pas dans ton code et ne les partage pas dans des espaces publics.

Comment générer ton token API

Étape 1: Dans ton admin Shopify, ouvre l’app Cowlendar.

Étape 2: Va dans Settings > Public API.

Étape 3: Clique sur Generate token.

Étape 4: Donne à ton token un nom descriptif pour pouvoir le reconnaître plus tard, par exemple "HubSpot sync", "Zapier" ou "Mobile app".

Étape 5: Clique sur Generate. Cowlendar te montre le token complet une seule fois. Copie-le tout de suite et stocke-le dans un endroit sûr, comme un gestionnaire de mots de passe ou les variables d’environnement de ton serveur.

Tu peux révoquer n’importe quel token à tout moment depuis la même page. La révocation coupe immédiatement toutes les requêtes API qui l’utilisent.

Utiliser ton token

Inclue le token dans le header Authorization de chaque requête API:

Authorization: Bearer YOUR_TOKEN_HERE

Exemple avec curl:

curl https://app.cowlendar.com/public-api/v1/services -H "Authorization: Bearer YOUR_TOKEN_HERE"

Si le token manque ou s’il est invalide, l’API renvoie 401.

Endpoints API

Base URL: https://app.cowlendar.com

Lister les services

GET /public-api/v1/services

Renvoie tous les services non archivés de ta boutique. Utilise cet endpoint pour récupérer tes IDs de service, types, durées, membres d’équipe, équipements et catégories de participants avant de créer des réservations via l’API.

Query parameters:

limit (optionnel, 1-100): nombre de résultats par page.

cursor (optionnel): curseur de pagination issu d’une réponse précédente.

is_active (optionnel, true ou false): filtre les services actifs ou inactifs.

type (optionnel): filtre par type de service. Valeurs: classic-checkout, classic-no-checkout, multiday-checkout, multiday-no-checkout, multislot-checkout, multislot-no-checkout, fullday-checkout, fullday-no-checkout.

q (optionnel, 120 caractères max): recherche de services par titre.

sort (optionnel): -id par défaut, les plus récents d’abord, id les plus anciens d’abord, title de A à Z, -title de Z à A.

Exemple de requête:

curl "https://app.cowlendar.com/public-api/v1/services?is_active=true&limit=10" -H "Authorization: Bearer YOUR_TOKEN_HERE"

Exemple de réponse, raccourci:

{
  "data": [
    {
      "id": "6789abcdef0123456789abcd",
      "title": "Haircut",
      "type": "classic-checkout",
      "is_active": true,
      "timezone": "Europe/Paris",
      "durations": [30, 45, 60],
      "default_duration": 30,
      "avs_type": "teammates",
      "meeting_location": "in_person",
      "enable_participants": false,
      "participants": [],
      "equipments": [],
      "teammates": [
        {
          "id": "aaa111bbb222ccc333ddd444",
          "firstname": "Marie",
          "lastname": "Dupont",
          "email": "[email protected]",
          "thumbnail": null
        }
      ],
      "product": {
        "handle": "haircut",
        "title": "Haircut",
        "image": "https://cdn.shopify.com/..."
      },
      "created_at": "2025-09-01T10:00:00.000Z",
      "updated_at": "2026-05-10T08:30:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Comprendre les champs clés d’un service

avs_type t’indique comment le service gère sa disponibilité et détermine si tu dois passer un teammate_id lors de la création d’une réservation:

avs_type: "teammates" signifie que chaque membre d’équipe a son propre planning indépendant. Quand tu crées une réservation, passe un teammate_id depuis le tableau teammates. Si tu ne l’envoies pas, le propriétaire de la boutique est utilisé comme solution de secours.

avs_type: "service" signifie que le service lui-même porte la disponibilité. Le membre assigné est déterminé automatiquement à partir de l’horaire de réservation. Tu peux quand même passer un teammate_id pour forcer l’assignation à une personne précise.

avs_type: "equipment" signifie que la disponibilité est gérée par équipement. C’est proche du mode service, mais lié à la capacité de l’équipement.

enable_participants t’indique si le service utilise des catégories de participants typées, comme "Adult", "Child" ou "Senior". Quand cette valeur est à true, le tableau participants contient ces catégories avec leurs IDs, leurs minimums, leurs maximums et leurs valeurs par défaut. Tu as besoin de ces IDs pour créer des réservations avec un détail précis des participants.

equipments contient les ressources réservables, comme des salles, des terrains, des véhicules ou des vélos, avec leurs variantes et leurs SKUs. Pour un équipement avec tracking_type: "same", toutes les unités sont interchangeables et tu peux utiliser n’importe quel SKU, généralement base. Pour tracking_type: "unique", chaque unité a son propre SKU et tu dois choisir un variants[].sku.

type t’indique le modèle de réservation. Le suffixe -checkout ou -no-checkout précise si le service utilise le checkout Shopify. Le préfixe indique le modèle de planning: classic pour un seul créneau, multiday pour plusieurs jours comme un séjour, multislot pour plusieurs créneaux consécutifs, et fullday pour une réservation sur la journée entière.

Lister les réservations

GET /public-api/v1/bookings

Renvoie les réservations de ta boutique. C’est l’endpoint à utiliser pour les synchronisations CRM, les exports de reporting et les tableaux de bord personnalisés.

Query parameters:

limit (optionnel, 1-100): résultats par page.

cursor (optionnel): curseur de pagination.

start (optionnel, date ISO 8601): uniquement les réservations qui commencent à cette date ou après.

end (optionnel, date ISO 8601): uniquement les réservations qui commencent avant cette date.

service_id (optionnel, tableau d’IDs): filtre un ou plusieurs services.

subscription_id (optionnel, tableau d’IDs): filtre les abonnements.

status (optionnel, tableau): confirmed, pending, declined, canceled.

attendance (optionnel, tableau): booked, pending, arrived, started, completed, no-show, delayed, paid.

customer_email (optionnel): filtre par e-mail client exact.

sort (optionnel): -id par défaut, plus récents d’abord, id plus anciens d’abord, start_date les plus tôt d’abord, -start_date les plus récents d’abord.

Exemple: récupérer toutes les réservations confirmées de la semaine prochaine:

curl "https://app.cowlendar.com/public-api/v1/bookings?status=confirmed&start=2026-05-25T00:00:00Z&end=2026-06-01T00:00:00Z&sort=start_date" -H "Authorization: Bearer YOUR_TOKEN_HERE"

Exemple: retrouver toutes les réservations d’un client donné:

curl "https://app.cowlendar.com/public-api/v1/[email protected]" -H "Authorization: Bearer YOUR_TOKEN_HERE"

Exemple: exporter tous les no-shows d’un service précis:

curl "https://app.cowlendar.com/public-api/v1/bookings?attendance=no-show&service_id=6789abcdef0123456789abcd" -H "Authorization: Bearer YOUR_TOKEN_HERE"

Exemple de réponse, raccourci:

{
  "data": [
    {
      "id": "abc123def456ghi789jkl012",
      "booking_str": "COW-1234",
      "service": {
        "id": "6789abcdef0123456789abcd",
        "title": "Haircut",
        "type": "classic-checkout"
      },
      "start_date": "2026-05-27T14:00:00.000Z",
      "end_date": "2026-05-27T14:30:00.000Z",
      "timezone": "Europe/Paris",
      "customer": {
        "name": "Jane Smith",
        "email": "[email protected]",
        "phone": "+33612345678",
        "locale": "en"
      },
      "form_data": {
        "Special requests": "Window seat"
      },
      "quantity": 1,
      "unit_quantity": 1,
      "quantity_details": [],
      "price": { "amount": 35, "currency": "EUR" },
      "confirmation_status": "confirmed",
      "attendance": "booked",
      "financial_status": "paid",
      "is_canceled": false,
      "teammates": [
        {
          "id": "aaa111bbb222ccc333ddd444",
          "firstname": "Marie",
          "lastname": "Dupont"
        }
      ],
      "order_id": "gid://shopify/Order/123456789",
      "subscription_id": null,
      "created_at": "2026-05-20T09:15:00.000Z",
      "updated_at": "2026-05-20T09:15:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Comprendre les champs clés d’une réservation

quantity et unit_quantity fonctionnent ensemble. Pour un service classic, comme une coupe, quantity correspond au nombre de clients présents et unit_quantity vaut 1. Pour un service multiday, comme un séjour, quantity correspond au nombre de chambres et unit_quantity au nombre de nuits. Pour un service multislot, quantity vaut toujours 1 et unit_quantity correspond au nombre de créneaux réservés. Le total des unités facturables est toujours quantity x unit_quantity.

quantity_details est le détail fin. Il peut contenir trois types d’entrées: default pour un compte anonyme, participant pour un participant typé comme "Adult" ou "Child", et equipment pour une ressource réservable comme "Court 3". Les anciennes réservations peuvent avoir un tableau vide ici.

confirmation_status peut être confirmed, pending ou declined. Certains services nécessitent une confirmation manuelle par l’admin avant qu’une réservation soit active.

attendance suit le cycle de présence du client: booked, pending, arrived, started, completed, no-show, delayed, paid.

order_id correspond à l’ID de commande Shopify quand la réservation est passée par le checkout Shopify. Il vaut null pour les réservations manuelles et pour les réservations créées via l’API.

subscription_id relie la réservation à un plan d’abonnement, par exemple un pass de 10 cours.

Créer une réservation via l’API

POST /public-api/v1/bookings

Crée une réservation de façon programmatique. Elle est traitée comme une manual booking, ce qui veut dire qu’aucune commande Shopify n’est créée. En revanche, toutes les automatisations habituelles se déclenchent normalement: e-mails de confirmation au client, e-mails et SMS à l’équipe, et synchronisation calendrier avec Google Calendar ou Outlook.

Cet endpoint est celui à utiliser si tu construis un frontend de réservation personnalisé, une app mobile, une borne, ou si tu importes des réservations depuis un autre système.

Champs requis:

service_id (string): l’ID du service, à récupérer via List Services.

start_date (date ISO 8601): début de la réservation.

end_date (date ISO 8601): fin de la réservation.

timezone (string): fuseau horaire IANA, par exemple Europe/Paris, America/New_York, Asia/Tokyo.

customer (object): doit contenir au minimum email ou phone. Il peut aussi inclure name, firstname, lastname et locale, qui est le code langue pour les e-mails envoyés au client.

Champs optionnels:

quantity (integer, défaut 1): unités principales réservées. Ignoré si quantity_details est fourni.

unit_quantity (integer, défaut 1): sous-unités par unité principale.

quantity_details (array): détail par type de participant ou équipement. Quand il est fourni, quantity est calculé automatiquement comme la somme.

teammate_id (string): force l’assignation à un membre précis de l’équipe.

subscription_id (string): relie cette réservation à un abonnement existant et déduit un crédit.

form_data (object): paires clé ou valeur personnalisées issues de ton formulaire.

price (number, défaut 0): prix total net de la réservation.

currency (string): code ISO 4217 comme USD, EUR ou GBP. Par défaut, l’API utilise la devise de ta boutique.

Exemple: créer une réservation simple

Un client réserve une coupe de 30 minutes avec un coiffeur précis:

curl -X POST https://app.cowlendar.com/public-api/v1/bookings -H "Authorization: Bearer YOUR_TOKEN_HERE" -H "Content-Type: application/json" -d '{
  "service_id": "6789abcdef0123456789abcd",
  "start_date": "2026-06-01T10:00:00.000Z",
  "end_date": "2026-06-01T10:30:00.000Z",
  "timezone": "Europe/Paris",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "+33612345678",
    "locale": "en"
  },
  "teammate_id": "aaa111bbb222ccc333ddd444",
  "quantity": 1,
  "price": 35,
  "currency": "EUR"
}'

Cowlendar crée la réservation et déclenche l’e-mail de confirmation, le SMS et l’invitation calendrier pour le client comme pour le membre d’équipe.

Exemple: réservation de groupe avec participants typés

Une famille réserve une visite guidée: 3 adultes et 2 enfants avec des prix différents:

curl -X POST https://app.cowlendar.com/public-api/v1/bookings -H "Authorization: Bearer YOUR_TOKEN_HERE" -H "Content-Type: application/json" -d '{
  "service_id": "6789abcdef0123456789abcd",
  "start_date": "2026-06-15T09:00:00.000Z",
  "end_date": "2026-06-15T11:00:00.000Z",
  "timezone": "America/New_York",
  "customer": {
    "email": "[email protected]",
    "firstname": "Sarah",
    "lastname": "Miller",
    "phone": "+15551234567",
    "locale": "en"
  },
  "quantity_details": [
    {
      "type": "participant",
      "name": "Adult",
      "quantity": 3,
      "participant_id": "adult_id_from_service"
    },
    {
      "type": "participant",
      "name": "Child (under 12)",
      "quantity": 2,
      "participant_id": "child_id_from_service"
    }
  ],
  "price": 175,
  "currency": "USD"
}'

Les valeurs participant_id viennent du tableau participants[] du service dans la réponse List Services. Le total de quantity est automatiquement fixé à 5, soit 3 + 2.

Exemple: réservation avec équipement

Un client réserve un court de tennis pendant 1 heure:

curl -X POST https://app.cowlendar.com/public-api/v1/bookings -H "Authorization: Bearer YOUR_TOKEN_HERE" -H "Content-Type: application/json" -d '{
  "service_id": "6789abcdef0123456789abcd",
  "start_date": "2026-06-10T16:00:00.000Z",
  "end_date": "2026-06-10T17:00:00.000Z",
  "timezone": "Europe/London",
  "customer": {
    "email": "[email protected]",
    "name": "Tom Wilson"
  },
  "quantity_details": [
    {
      "type": "equipment",
      "name": "Court 3",
      "quantity": 1,
      "equipment_id": "eee555fff666ggg777hhh888",
      "equipment_sku": "COURT3",
      "capacity": 4
    }
  ],
  "price": 25,
  "currency": "GBP"
}'

Les valeurs equipment_id et equipment_sku viennent du tableau equipments[] du service. Pour un équipement avec tracking_type: "same", utilise n’importe quel SKU, en général base. Pour tracking_type: "unique", utilise le variants[].sku spécifique à l’unité voulue.

Exemple: réservation liée à un abonnement

Un membre d’un studio de yoga utilise un crédit de son pass mensuel de 10 cours:

curl -X POST https://app.cowlendar.com/public-api/v1/bookings -H "Authorization: Bearer YOUR_TOKEN_HERE" -H "Content-Type: application/json" -d '{
  "service_id": "6789abcdef0123456789abcd",
  "start_date": "2026-06-05T08:00:00.000Z",
  "end_date": "2026-06-05T09:00:00.000Z",
  "timezone": "America/Los_Angeles",
  "customer": {
    "email": "[email protected]",
    "name": "Lisa Chen",
    "locale": "en"
  },
  "subscription_id": "fff000eee111ddd222ccc333",
  "price": 0
}'

L’abonnement doit être active, appartenir au même service et avoir remaining_credits > 0. Cowlendar décrémente automatiquement le crédit restant et envoie l’e-mail de mise à jour d’abonnement au client.

Codes d’erreur

400 Erreur de validation. Un champ requis manque ou un champ a un mauvais format. Le body d’erreur t’indique quel champ pose problème.

401 Token manquant ou invalide.

403 Boutique inactive ou accès restreint.

404 Service introuvable.

422 Réservation rejetée. Le créneau est déjà pris, le membre d’équipe n’est pas disponible, l’équipement a atteint sa capacité, ou l’abonnement n’a plus de crédits. Vérifie le message d’erreur pour connaître la raison précise.

429 Rate limit dépassé. Espace un peu tes requêtes et réessaie après un court instant.

Pagination

Tous les endpoints de liste utilisent une pagination par curseur. Quand la réponse contient "has_more": true, passe la valeur next_cursor dans le paramètre cursor de la requête suivante:

curl "https://app.cowlendar.com/public-api/v1/bookings?cursor=eyJpZCI6IjY3ODlhYmNkIn0=&limit=50" -H "Authorization: Bearer YOUR_TOKEN_HERE"

L’ordre de tri est conservé d’une page à l’autre. La taille maximale d’une page est de 100 résultats.

Webhooks: notifications de réservation en temps réel

Alors que l’API te permet d’aller chercher les données à la demande, les webhooks te les poussent immédiatement. Chaque fois qu’une réservation est créée, confirmée, annulée ou reprogrammée, Cowlendar envoie un HTTP POST signé vers l’URL que tu as configurée.

Les webhooks sont essentiels pour les intégrations en temps réel: synchros CRM, notifications Slack, séquences e-mail automatisées, dashboards live, ou tout workflow qui doit réagir dès qu’un événement de réservation se produit.

Configurer un endpoint webhook

Étape 1: Dans ton admin Shopify, ouvre l’app Cowlendar.

Étape 2: Va dans Settings > Webhooks.

Étape 3: Clique sur Add endpoint.

Étape 4: Saisis un nom pour ton endpoint, par exemple "HubSpot CRM", "Zapier" ou "Analytics pipeline".

Étape 5: Colle ton HTTPS URL. L’URL doit impérativement utiliser HTTPS. Si tu utilises Zapier ou Make, colle l’URL de webhook qu’ils te donnent.

Étape 6: Coche les événements que tu veux recevoir. Tu peux choisir n’importe quelle combinaison.

Étape 7: Clique sur Create.

Cowlendar affiche un signing secret qui commence par whsec_. Copie-le immédiatement et conserve-le en lieu sûr. Ce secret n’est affiché qu’une seule fois et tu en auras besoin pour vérifier les requêtes webhook entrantes sur ton serveur.

Tu peux modifier plus tard n’importe quel endpoint pour changer l’URL ou activer et désactiver certains événements:

Les 8 événements webhook

booking.created se déclenche quand une nouvelle réservation est créée depuis n’importe quelle source: le widget storefront, le panneau admin, le POS ou la Public API.

booking.confirmed se déclenche quand une réservation en attente est confirmée manuellement par l’admin.

booking.declined se déclenche quand une réservation en attente est refusée.

booking.canceled se déclenche quand une réservation est annulée par le client ou par l’admin.

booking.rescheduled se déclenche quand la date d’une réservation ou les membres d’équipe assignés changent.

booking.attendance_changed se déclenche quand le statut de présence change, par exemple de "booked" à "completed" ou lorsqu’il est marqué "no-show".

subscription.created se déclenche quand un nouvel abonnement récurrent est créé.

subscription.billing_failed se déclenche quand une tentative de facturation d’abonnement échoue. Après 3 échecs consécutifs, le contrat d’abonnement est automatiquement annulé sur Shopify et le statut local passe à canceled.

À quoi ressemble le payload d’un webhook

Chaque livraison webhook arrive sous forme de HTTP POST avec un body JSON. Voici un exemple complet de booking.created:

{
  "id": "evt_2b86f80a-1c3d-4e5f-9a8b-7c6d5e4f3a2b",
  "type": "booking.created",
  "created_at": "2026-05-20T09:15:00.000Z",
  "shop_domain": "yourshop.myshopify.com",
  "data": {
    "id": "abc123def456ghi789jkl012",
    "booking_str": "COW-1234",
    "service": {
      "id": "6789abcdef0123456789abcd",
      "title": "Haircut",
      "type": "classic-checkout"
    },
    "start_date": "2026-05-27T14:00:00.000Z",
    "end_date": "2026-05-27T14:30:00.000Z",
    "timezone": "Europe/Paris",
    "customer": {
      "name": "Jane Smith",
      "email": "[email protected]",
      "phone": "+33612345678",
      "locale": "en"
    },
    "form_data": {},
    "quantity": 1,
    "unit_quantity": 1,
    "quantity_details": [],
    "price": { "amount": 35, "currency": "EUR" },
    "confirmation_status": "confirmed",
    "attendance": "booked",
    "financial_status": null,
    "is_canceled": false,
    "teammates": [
      {
        "id": "aaa111bbb222ccc333ddd444",
        "firstname": "Marie",
        "lastname": "Dupont"
      }
    ],
    "order_id": null,
    "subscription_id": null,
    "created_at": "2026-05-20T09:15:00.000Z",
    "updated_at": "2026-05-20T09:15:00.000Z"
  }
}

Le champ data contient l’objet de réservation ou d’abonnement complet, exactement dans la même structure que la réponse API.

Pour les événements subscription.billing_failed, le payload inclut en plus un objet previous contenant le failure_count avant la tentative actuelle. Cela te permet de suivre l’escalade, par exemple en envoyant un e-mail urgent après le deuxième échec.

Headers présents sur chaque livraison webhook

X-Cowlendar-Event-Id est l’ID unique de l’événement. Cowlendar réutilise le même ID lorsqu’il retente une livraison échouée. Utilise-le pour dédupliquer de ton côté.

X-Cowlendar-Event-Type est la chaîne du type d’événement, par exemple booking.created.

X-Cowlendar-Timestamp est le timestamp Unix en secondes au moment où Cowlendar a signé la requête.

X-Cowlendar-Signature est la signature HMAC-SHA256 au format t=<timestamp>,v1=<hex>.

Vérifier la signature du webhook

Chaque requête webhook est signée afin que tu puisses confirmer qu’elle vient bien de Cowlendar et qu’elle n’a pas été altérée. La signature est calculée comme HMAC-SHA256(secret, timestamp + "." + raw_body) à l’aide du signing secret de ton endpoint.

Tu devrais aussi rejeter les requêtes dont le timestamp date de plus de 5 minutes afin d’éviter les replay attacks.

⚠️Warning

Calcule toujours la signature sur le RAW request body, c’est-à-dire les octets exacts envoyés par Cowlendar, et non sur un objet JSON parsé puis re-sérialisé. Le parsing et la re-sérialisation peuvent changer les espaces ou l’ordre des clés, ce qui casse la signature.

Node.js (Express):

import crypto from "crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/cowlendar",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sigHeader =
      req.header("X-Cowlendar-Signature") || "";
    const timestamp =
      req.header("X-Cowlendar-Timestamp") || "";
    const rawBody = req.body.toString("utf8");

    // Reject requests older than 5 minutes
    if (
      Math.abs(Date.now() / 1000 - parseInt(timestamp, 10))
      > 300
    ) {
      return res.status(400).send("Timestamp too old");
    }

    const expected = crypto
      .createHmac(
        "sha256",
        process.env.COWLENDAR_WEBHOOK_SECRET
      )
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

    const received = sigHeader
      .split(",")
      .find((p) => p.startsWith("v1="))
      ?.slice(3);

    if (
      !received ||
      !crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(received)
      )
    ) {
      return res.status(401).send("Invalid signature");
    }

    const event = JSON.parse(rawBody);

    // Short-circuit test pings
    if (event.type === "webhook.ping") {
      return res.status(200).send("pong");
    }

    // Handle real events here
    res.status(200).send("ok");
  }
);

Python (Flask):

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

app = Flask(__name__)

@app.post("/webhooks/cowlendar")
def cowlendar_webhook():
    sig_header = request.headers.get(
        "X-Cowlendar-Signature", ""
    )
    timestamp = request.headers.get(
        "X-Cowlendar-Timestamp", ""
    )
    raw_body = request.get_data(as_text=True)

    # Reject requests older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return "Timestamp too old", 400

    expected = hmac.new(
        os.environ["COWLENDAR_WEBHOOK_SECRET"].encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()

    received = next(
        (p[3:] for p in sig_header.split(",")
         if p.startswith("v1=")),
        None,
    )
    if not received or not hmac.compare_digest(
        expected, received
    ):
        return "Invalid signature", 401

    event = json.loads(raw_body)

    if event["type"] == "webhook.ping":
        return "pong", 200

    # Handle real events here
    return "ok", 200

PHP:

<?php
$secret = getenv("COWLENDAR_WEBHOOK_SECRET");

$rawBody   = file_get_contents("php://input");
$sigHeader = $_SERVER["HTTP_X_COWLENDAR_SIGNATURE"] ?? "";
$timestamp = $_SERVER["HTTP_X_COWLENDAR_TIMESTAMP"] ?? "";

// Reject requests older than 5 minutes
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(400);
    exit("Timestamp too old");
}

$expected = hash_hmac(
    "sha256",
    $timestamp . "." . $rawBody,
    $secret
);

$received = null;
foreach (explode(",", $sigHeader) as $part) {
    if (str_starts_with($part, "v1=")) {
        $received = substr($part, 3);
        break;
    }
}

if (!$received || !hash_equals($expected, $received)) {
    http_response_code(401);
    exit("Invalid signature");
}

$event = json_decode($rawBody, true);

if ($event["type"] === "webhook.ping") {
    http_response_code(200);
    exit("pong");
}

// Handle real events here
http_response_code(200);
echo "ok";

Tester ton webhook avant la mise en production

Chaque endpoint webhook dispose d’un bouton Test dans l’admin. Quand tu cliques dessus, il envoie un événement synthétique webhook.ping à ton URL. Cet événement utilise la même signature, les mêmes headers et le même comportement de retry que les événements réels, mais avec un payload de test sans risque:

{
  "id": "evt_2b86f80a...",
  "type": "webhook.ping",
  "created_at": "2026-05-13T14:57:57.704Z",
  "shop_domain": "yourshop.myshopify.com",
  "data": {
    "message": "This is a test event from Cowlendar. If you can read this, your endpoint is reachable."
  }
}

Utilise-le pour confirmer que Cowlendar peut joindre ton URL, que DNS, HTTPS et le firewall fonctionnent bien, et pour valider ton code de vérification de signature HMAC sans créer de vraie réservation. Une vraie réservation enverrait des e-mails à un client, créerait des événements calendrier et pourrait même déclencher une commande Shopify.

Après avoir cliqué sur Test, vérifie le bouton See deliveries pour voir le code HTTP renvoyé par ton endpoint. Un 200 vert signifie que tout fonctionne.

Comportement de retry et désactivation automatique

Si ton endpoint renvoie une erreur 5xx, un 429 ou un timeout réseau, Cowlendar retente selon ce calendrier:

Après 1 minute, après 5 minutes, après 25 minutes, après 2 heures, après 10 heures et après 50 heures. Cela fait 6 tentatives au total sur environ 3 jours.

Après environ 20 échecs consécutifs, tous événements confondus, l’endpoint est automatiquement désactivé et Cowlendar envoie un e-mail au propriétaire de la boutique. Tu pourras le réactiver dans Settings > Webhooks une fois ton serveur revenu en ligne.

Le même X-Cowlendar-Event-Id est réutilisé lors des retries. Stocke toujours les IDs déjà traités et ignore les doublons.

Toute réponse 2xx est considérée comme un succès. Tu n’as pas besoin de renvoyer un body ou un content type particulier.

Bonnes pratiques pour les webhooks

Réponds en moins de 10 secondes. Si ton handler doit faire du travail lourd, comme appeler une autre API, écrire en base ou lancer une opération complexe, fais-le de manière asynchrone. Accepte immédiatement le webhook avec un 200, puis traite-le dans un background job ou une file.

Déduplique avec l’event ID. Stocke chaque X-Cowlendar-Event-Id traité. Si tu reçois le même ID une nouvelle fois, saute-le. Cowlendar réessaie avec le même ID en cas d’échec.

Utilise une comparaison en temps constant pour les signatures. crypto.timingSafeEqual en Node.js, hmac.compare_digest en Python et hash_equals en PHP. Une comparaison de chaînes classique comme === est vulnérable aux timing attacks.

Ne fais pas de retry de ton côté. Cowlendar gère déjà les retries. Si ton serveur a un souci temporaire, renvoie 5xx et Cowlendar reviendra selon son propre planning.

Gère webhook.ping explicitement. Renvoie 200 immédiatement pour les événements ping. Cela te permet d’utiliser le bouton Test sans déclencher ta logique métier.

Limites actuelles

Les réservations créées via l’API sont des manual bookings. Elles ne créent pas de commande Shopify. Si ton service utilise normalement le checkout Shopify, l’API le contourne. Les e-mails de confirmation, les SMS et la synchronisation calendrier fonctionnent quand même normalement.

Pas encore d’endpoint de disponibilité. L’API actuelle te permet de lire les services, lire les réservations et créer des réservations. Elle n’expose pas les créneaux disponibles. Pour savoir si un créneau est libre, tente la création de réservation et gère la réponse 422 si le créneau est déjà pris. Un endpoint de disponibilité pourrait arriver plus tard.

Pas encore d’endpoint de mise à jour ou de suppression. Tu peux créer et lire des réservations, mais pas les modifier, les reprogrammer ni les annuler via l’API. Pour l’instant, ces actions doivent être gérées dans l’admin Cowlendar.

Des rate limits s’appliquent. Si tu envoies trop de requêtes dans une fenêtre courte, l’API renvoie 429. Pour les opérations volumineuses, comme l’export complet des réservations, ajoute un léger délai entre les requêtes paginées, par exemple 200 à 500 ms.

Les webhook secrets ne sont affichés qu’une seule fois. Si tu perds ton signing secret, supprime l’endpoint et recrée-en un nouveau pour obtenir un secret neuf.

Les webhooks exigent HTTPS. Les endpoints HTTP ne sont pas acceptés.

FAQ

Puis-je utiliser l’API Cowlendar avec Zapier ou Make sans écrire de code?

Oui. Pour les webhooks, c’est-à-dire recevoir des événements depuis Cowlendar, crée un trigger "Custom Webhook" dans Zapier ou Make, copie l’URL qu’ils te donnent et ajoute-la comme endpoint dans Cowlendar Settings > Webhooks. Chaque événement de réservation déclenchera ton automatisation. Pour l’API, donc envoyer des requêtes vers Cowlendar, utilise l’action "HTTP Request" dans Zapier ou Make pour appeler n’importe quel endpoint Cowlendar avec ton Bearer token.

Les réservations créées via l’API envoient-elles des e-mails aux clients?

Oui. Les réservations créées via l’API sont traitées exactement comme des réservations manuelles. Les e-mails de confirmation, les notifications SMS et la synchronisation calendrier se déclenchent automatiquement, comme pour une réservation créée depuis le panneau admin.

Que se passe-t-il si mon endpoint webhook tombe?

Cowlendar retente les livraisons échouées 6 fois sur environ 3 jours. Après une vingtaine d’échecs consécutifs, l’endpoint est automatiquement désactivé et tu reçois un e-mail. Réactive-le dans Settings > Webhooks quand ton serveur est de nouveau stable.

Puis-je avoir plusieurs endpoints webhook?

Oui. Tu peux en créer autant que nécessaire, chacun avec sa propre sélection d’événements et sa propre URL. Par exemple, un endpoint pour ton CRM écoutant booking.created et booking.canceled, et un autre pour ton pipeline analytics écoutant tous les événements.

Puis-je révoquer un token API?

Oui. Va dans Settings > Public API et clique sur le bouton Revoke. Le token cesse de fonctionner immédiatement.

Existe-t-il un sandbox ou un environnement de staging?

Pas pour le moment. Utilise le bouton Test de webhook.ping pour valider ta configuration webhook sans créer de vraies réservations. Pour les tests API, nous te recommandons de créer un service de test dans ton admin Cowlendar et de l’utiliser uniquement pour le développement.

Où trouver la référence API complète?

La documentation API interactive, avec tous les schémas, paramètres et exemples de réponse, se trouve sur https://app.cowlendar.com/public-api/docs