Webhooks

Les webhooks envoient les achats de produits de Curling IO à Zapier, à n8n ou à un autre point de terminaison HTTPS public. Les webhooks sont une fonctionnalité Premium.

Allez à Intégrations > Webhooks dans l’espace d’administration, puis sélectionnez Nouveau Webhook.

Créer un webhook

Entrez un nom et l’URL HTTPS du destinataire. Laissez Activé désactivé tant que vous n’avez pas envoyé de test et confirmé que le destinataire l’a traité correctement.

Chaque webhook a sa propre notification, sa sélection de produits, sa destination et sa sélection de champs. Créez un autre webhook si un destinataire a besoin d’une notification, d’une sélection de produits, d’une destination ou d’une charge utile différente.

Choisir quand envoyer

Choisissez une option sous Quand envoyer :

• Un produit est soumis : envoie la notification après la finalisation de la commande, y compris pour les produits gratuits et ceux payés immédiatement.
• Un produit est payé en totalité : envoie la notification la première fois que la ligne de produit est entièrement payée.
• Un produit est annulé : envoie la notification lorsqu’une affectation de remboursement annule la ligne de produit. Une réduction n’envoie pas cette notification.
• Un produit est replanifié : envoie la notification lorsqu’un administrateur change l’heure de début d’un produit acheté dans le calendrier.

Si le destinataire a besoin de plusieurs notifications, créez un webhook pour chacune. Ils peuvent utiliser la même URL de destination.

Choisir les produits qui peuvent envoyer une notification

Choisissez une portée sous Produits à envoyer :

• Tous les produits
• Types de produits correspondants
• Tout produit sélectionné

Si vous sélectionnez plusieurs types de produits ou produits, une correspondance avec l’un d’eux suffit. Les locations et les extras fonctionnent comme les autres produits. Par exemple, sélectionnez le type de produit Locations pour envoyer chaque achat de location, ou sélectionnez quatre produits de location pour envoyer seulement les achats de ces quatre produits.

Choisir les champs à envoyer

Champs à envoyer détermine les données d’achat enregistrées avec la livraison et envoyées à la destination. Les nouveaux webhooks ont 16 champs recommandés sélectionnés, qui couvrent la commande, l’inscription, le produit, la tarification et l’horaire. Les renseignements sur l’acheteur et le participant ne sont pas sélectionnés par défaut.

Utilisez les groupes ou la recherche pour trouver un champ. Sélectionner le groupe ajoute tous les champs du groupe ouvert, Effacer le groupe les retire et Sélectionner les champs recommandés rétablit la sélection par défaut. L’aperçu de la charge utile se met à jour immédiatement. Vous devez sélectionner au moins un champ.

Les groupes disponibles sont :

• Commande : ID de commande.
• Inscription : ID de l’inscription, ID de l’inscription parente et statut.
• Produit : ID du produit, nom, ID du type de produit et nom du type.
• Acheteur : nom et courriel de l’acheteur.
• Participant : ID, nom et date de naissance du participant.
• Tarification : quantité, prix unitaire, total et devise.
• Horaire et ressources : début, fin, fuseau horaire, ressources et noms des ressources.
• Formulaire du participant : champs du participant et questions personnalisées pour les participants configurés par l’organisation.
• Formulaire d’inscription : questions d’inscription personnalisées utilisées par les produits de l’organisation.

Les champs de l’acheteur et du participant portent la mention Sensible. Les questions personnalisées des participants et des inscriptions portent la mention Peut être sensible, car leur contenu dépend de la question. Sélectionner l’un ou l’autre affiche un avertissement sans empêcher l’enregistrement. Votre organisation doit confirmer que la destination est autorisée à recevoir les renseignements sélectionnés.

Curling IO accepte seulement les URL de destination HTTPS publiques. La requête est donc chiffrée pendant son trajet de Curling IO au destinataire. HTTPS ne contrôle pas ce qui arrive après la livraison. Curling IO ne contrôle pas la façon dont Zapier, n8n ou un autre service destinataire stocke, utilise, conserve ou partage les données, et n’est pas responsable de ce traitement par un tiers. Votre organisation doit choisir le service et décider quels champs lui envoyer.

Les mots de passe, les jetons d’authentification, les données de cartes de paiement, les secrets des fournisseurs de paiement, les notes internes, les pièces jointes, les inscriptions sans lien et les dossiers de clients sans lien ne peuvent pas être sélectionnés. Curling IO ne conserve pas les mots de passe des comptes.

Si une question personnalisée enregistrée est ensuite supprimée de l’organisation, l’éditeur du webhook indique que ce champ sélectionné est indisponible au lieu de le remplacer sans vous en avertir.

Configurer Zapier

Webhooks by Zapier est une application Premium de Zapier et exige un forfait Zapier payant.

1. Créez un Zap et choisissez Webhooks by Zapier comme déclencheur.
2. Choisissez Catch Hook. Curling IO envoie du JSON analysé; Catch Raw Hook n’est donc normalement pas nécessaire.
3. Copiez l’URL du webhook affichée par Zapier.
4. Dans Curling IO, créez un webhook désactivé et collez l’URL dans URL de destination.
5. Choisissez les champs nécessaires au Zap, enregistrez le webhook, puis sélectionnez Envoyer un test.
6. Revenez à Zapier et sélectionnez Test trigger. Vérifiez l’enregistrement reçu et associez ses champs aux étapes suivantes.
7. Publiez le Zap, puis activez le webhook dans Curling IO.

La sélection recommandée comprend resources, un tableau contenant les ID et les noms des ressources, et resource_names, les mêmes noms sous forme de texte séparé par des virgules. La livraison de test comprend deux ressources pour que Zapier puisse découvrir les champs répétés des ressources.

Zapier donne à chaque Catch Hook une URL difficile à deviner. Traitez cette URL comme un mot de passe. Toute personne qui l’a peut déclencher le Zap. Zapier peut retourner 404 lorsque le Zap destinataire est désactivé ou supprimé. Consultez la documentation des webhooks de Zapier.

Configurer n8n

1. Ajoutez un nœud Webhook n8n à un flux de travail et réglez sa méthode HTTP sur POST.
2. Sélectionnez Listen for test event, puis copiez l’URL de test HTTPS.
3. Créez dans Curling IO un webhook désactivé avec cette URL et choisissez les champs nécessaires au flux de travail.
4. Enregistrez le webhook et sélectionnez Envoyer un test pendant que n8n est à l’écoute.
5. Confirmez que n8n a reçu un objet JSON, puis associez ses champs aux nœuds suivants.
6. Copiez l’URL de production du nœud webhook dans Curling IO et enregistrez la modification.
7. Activez le flux de travail n8n, puis le webhook Curling IO.

L’URL de test n8n fonctionne seulement lorsque l’éditeur est à l’écoute. L’URL de production fonctionne lorsque le flux de travail est actif. Un point de terminaison n8n autohébergé doit être accessible sur Internet par HTTPS. Consultez la documentation officielle du nœud Webhook de n8n.

Tester avant d’activer

Envoyer un test envoie un achat de location représentatif par les mêmes mécanismes de construction de la charge utile, de mise en file, de requête HTTP, de nouvelle tentative et de signature qu’une vraie notification. Le test utilise la sélection de champs enregistrée du webhook, ignore le filtre de produits et peut être envoyé pendant que le webhook est désactivé, tant qu’il n’a pas été supprimé. Un test en attente n’est pas envoyé si vous supprimez le webhook avant son exécution. La charge utile contient test: true, ce qui permet à un destinataire personnalisé de séparer les tests du travail réel.

Après avoir changé la sélection de champs, vous devez enregistrer le webhook avant d’envoyer un autre test.

Livraison et nouvelles tentatives

Curling IO envoie un objet JSON avec Content-Type: application/json. Toute réponse 2xx est un succès. Les échecs réseau, les délais d’attente dépassés et les réponses 408, 429 et 5xx sont réessayés jusqu’à cinq fois. Les autres réponses 4xx échouent immédiatement. Chaque livraison a une limite totale de 20 tentatives, y compris les nouvelles tentatives manuelles. S’il reste moins de cinq tentatives, une reprise utilise seulement les appels restants. À 20 tentatives, vous ne pouvez plus réessayer cette livraison.

La livraison se fait au moins une fois. Un destinataire peut accepter une requête avant que Curling IO reçoive sa réponse. La même publication de webhook peut donc arriver plusieurs fois. Éliminez les doublons avec le champ id de la charge utile. Ne vous fiez pas à l’ordre de livraison.

Chaque livraison conserve le corps exact de sa requête. Une nouvelle tentative envoie le même corps, même si la sélection du webhook, l’inscription, le participant, le produit ou l’horaire a changé depuis la livraison d’origine.

Les notifications de replanification attendent dix secondes avant la livraison. Si le même produit est replanifié pendant ce délai, Curling IO envoie seulement le dernier horaire à ce webhook. Chaque destination est traitée séparément. Un appel déjà commencé ne peut pas être remplacé. Les destinataires doivent donc tolérer les appels en double ou reçus dans le désordre. Sélectionnez ID de l’inscription et utilisez line_item_id si le destinataire a besoin d’une clé stable pour l’achat du produit.

La page d’administration affiche les 50 dernières livraisons de webhooks. Une livraison échouée conservée peut être remise en file manuellement si son webhook est activé, si sa charge utile est conservée et si moins de 20 tentatives ont été faites. Les charges utiles et les détails des livraisons sont supprimés après 30 jours.

La liste des livraisons affiche le résultat, le nombre de tentatives, l’état HTTP et la charge utile de la requête. Pour une livraison échouée conservée, sélectionnez Réessayer après avoir corrigé le destinataire.

Désactiver ou supprimer un webhook arrête les nouvelles notifications. Une livraison ordinaire en attente n’est pas envoyée à son prochain appel si le webhook est désactivé. Si Premium prend fin, Curling IO conserve la configuration, mais ne crée plus de tâches de webhook. Les appels déjà en file pendant que Premium était actif peuvent se terminer.

Charge utile

L’aperçu de la charge utile à côté de Champs à envoyer affiche le corps JSON pendant que vous modifiez la sélection. Il utilise des valeurs représentatives, sans renseignements provenant d’un achat réel, et n’envoie rien à la destination. Sélectionner un champ ajoute sa clé à l’aperçu. Désélectionner un champ retire sa clé.

L’exemple ci-dessus utilise une petite sélection pour que le corps complet soit visible. Chaque charge utile comprend les champs de livraison suivants, même s’ils ne sont pas sélectionnés. Vous ne pouvez pas les retirer :

• id : l’ID de publication du webhook utilisé pour éliminer les doublons.
• webhook_topic : le sujet de notification enregistré.
• version : la version du format de la charge utile.
• published_at : l’heure de publication UTC.
• test : indique si Envoyer un test a créé la livraison.

Les autres clés proviennent de Champs à envoyer. Les clés non sélectionnées sont omises. Une valeur scalaire sélectionnée sans valeur est null. Une collection sélectionnée sans valeur est un tableau vide. L’aperçu se met à jour avant l’enregistrement, mais Envoyer un test et les vraies notifications utilisent la dernière sélection enregistrée.

Cet exemple utilise la sélection recommandée :

{
  "id": "whp_opaque_publication_id",
  "webhook_topic": "line_item.submitted",
  "version": 1,
  "published_at": "2026-08-01T00:55:00Z",
  "test": false,
  "order_id": 501,
  "line_item_id": 902,
  "status": "submitted",
  "product_id": 73,
  "product_name": "Corporate Ice Rental",
  "product_type_id": 8,
  "product_type_name": "Rentals",
  "quantity": 1,
  "unit_price_cents": 24000,
  "total_cents": 24000,
  "currency": "CAD",
  "rental_start_at": "2026-08-08T00:00:00Z",
  "rental_end_at": "2026-08-08T01:00:00Z",
  "rental_time_zone": "America/Toronto",
  "resources": [
    { "id": 1, "name": "Sheet 1" },
    { "id": 2, "name": "Sheet 2" }
  ],
  "resource_names": "Sheet 1, Sheet 2"
}

Les réponses aux formulaires des participants et d’inscription utilisent des clés stables sans imbrication. Par exemple, une question de participant enregistrée comme accessibility est envoyée comme participant_question_accessibility. Une question d’inscription enregistrée comme event_name est envoyée comme registration_question_event_name.

Vérifier les signatures

Curling IO affiche un secret de signature après la création du webhook ou le renouvellement du secret. Copiez-le à ce moment, car il ne sera plus affiché.

L’en-tête curlingio-webhook-signature a cette forme :

t=1754009700,v1=hexadecimal_hmac

Pour le vérifier :

1. Lisez le corps brut de la requête sans l’analyser ni le reformater.
2. Joignez l’horodatage, un point et le corps brut : <timestamp>.<raw_request_body>.
3. Calculez le HMAC-SHA256 avec le secret de signature.
4. Comparez le résultat hexadécimal à v1 avec une comparaison en temps constant.
5. Rejetez les horodatages hors de la tolérance choisie pour limiter les attaques par rejeu.

La requête comprend aussi les en-têtes curlingio-webhook-topic, curlingio-webhook-publication, curlingio-webhook-delivery et curlingio-webhook-version. Renouveler le secret de signature invalide l’ancien secret pour les tentatives de livraison futures.