Webhooks
Webhooks
Qu'est ce que les webhooks ?
Prenons l’exemple de votre banque. Lorsque vous effectuez un retrait, le distributeur vérifie le solde restant sur votre compte et sort le montant que vous avez demandé. Une fois cette opération effectuée, votre solde est mis à jour. Ce changement de solde déclenche une action : un SMS vous est envoyé avec les détails du retrait. C’est de cette façon que fonctionnent les webhooks.
Un webhook permet de déclencher une action suite à un évènement. Ils sont généralement utilisés pour faire communiquer des systèmes. C’est la façon la plus simple de recevoir une alerte lorsque quelque chose se produit dans un autre système.
Les webhooks sont utilisés pour les notifications en temps réel, de sorte que votre système peut être mis à jour dès que l’événement se produit.
Les webhooks sont des points de rappel HTTP qui sont définis par l’utilisateur. Ils vous permettent d’enregistrer une URL où les données de l’événement peuvent être stockées. Ensuite, vous pourrez faire ce que vous voulez avec les données que vous récupérez et stockez d’un événement en déclenchant une action.
Avec des webhooks, vous pouvez entre autres :
Synchroniser les systèmes en temps réel
Envoyer n’importe quel type de notification
Traiter les données comme vous le souhaitez
Créer des rapports
...
Comment configurer un webhook ?
Prenons un exemple : Vous souhaitez stocker dans un fichier excel les contacts des personnes ayant passé une commande sur votre site.
Prérequis : Vous devez créer votre compte sur Make.
1. Créez un scénario en sélectionnant le trigger Custom Webhook.
2. Nommez le webhook.
3. Le webhook est en "écoute" : Copier l'**url** donnée par Make et gardez cette fenêtre ouverte.
Renseignez l'url donnée par Make dans l'application Ciklik.
Cliquez sur Mes Sites, puis Modifier.
Dans l'onglet Paramètres marketing, ajouter les clés et URL des webhooks associées au niveau du champ Webhooks.
4. Passez une commande sur votre site pour valider l'écoute du webhook et la remontée de données pour ce scénario.
5. Vous pouvez à présent construire votre scénario pour utiliser les données réceptionnées lors d'une prise de commande et conduire automatiquement les actions de votre choix.
Avant de créer une action, liez le trigger à un router. Cela vous permettra par la suite de déclencher plusieurs actions lors d'une prise de commande sans avoir à tout reparamétrer.
6. Sélectionnez à présent l'application que vous souhaitez pour conduire votre action.
Dans notre exemple, on cherche à récolter les informations dans une feuille excel.
Créez un fichier vierge dans votre drive et donnez-lui la structure souhaitée en définissant les valeurs des colonnes.
Il faut ensuite effectuer la connexion avec votre compte google.
Puis renseignez le nom du google sheet dans lequel seront rapatriées les données sélectionnées parmi la liste des valeurs remontées par l'application Ciklik via le webhook lors de la création d'une commande.
7. Validez votre scenario puis activez-le. Vous pouvez tester en passant une nouvelle commande sur votre site. Vous retrouverez automatiquement les valeurs des champs renseignés dans votre fichier excel.
Quels événements sont disponibles ?
Voici la liste des événements disponibles pour les webhooks depuis l'application Ciklik :
| Clé | |
|---|---|
| subscription | created\_subscription |
| updated\_subscription | |
| deleted\_subscription | |
| checkoutorder | created\_checkoutorder |
| updated\_checkoutorder | |
| checkouttransaction | created\_checkouttransaction |
| updated\_checkouttransaction | |
| checkoutinvoice | created\_checkoutinvoice |
| address | created\_address |
| updated\_address | |
| shippingbox | created\_shippingbox |
| updated\_shippingbox | |
| deleted\_shippingbox | |
| user | created\_user |
| upated\_user | |
| optin | created\_optin |
| updated\_optin |
Pour chacune de ces clés, un scénario peut être déclenché avec un webhook en renseignant son URL au niveau du champ Webhooks, dans l'onglet Paramètres marketing de votre site.
Retrouvez dans la rubrique Webhooks de la colonne de gauche le détail des données envoyées via les webhooks quand le scénario a été executé avec succès. ces données sont sauvegardées temporairement dans l'application.
Pour les mises à jour (updated), on retrouve la liste des champs modifiés et leur nouvelle valeur dans le tableau "changed" :
L'URL pour la gestion des paniers abandonnés est renseignée au niveau du champ Url Webhook : Paniers abandonnés.
Les logs de webhook sont accessibles depuis la rubrique Webhooks de la colonne de gauche et disponibles pendant 20 jours.
Quelles informations sont remontées ?
Sont renseignés dans chaque bloc de code ci-dessous les informations qui remontent via les webhooks, sous le format suivant :
| Valeur | Exemple | Note |
|---|---|---|
| "cart\_id" | 1042077 | // ID du panier |
Webhook Panier abandonné
"cart_id": 1042077, // ID du panier
"user_id": 133180, // ID du user ayant généré ce panier
"first_name": "JEANNE", // prénom du user ayant généré ce panier (from user profile)
"last_name": "MOULIN", // nom de famille du user ayant généré de panier (from user profile)
"phone": "0604000000", // telephone du user ayant généré ce panier (from user profile)
"email": "jeannemoulin06@gmail.com", // email du user ayant généré ce panier (from user profile)
"created": "2021-01-17T21:05:47.000000Z", // timestamp de la création du panier
"item": "Box 3 mois" // formule présente dans le panierWebhook de création d'un nouvel abonnement
{
"order_id": 230129, // ID commande
"user_id": 122312, // UUID user (client)
"first_name": "ANNE", // prénom client (from profile)
"last_name": "DUPOND", // nom de famille client (from profile)
"phone": "0600000000", // telephone client, from checkout
"email": "annedupond@gmail.com", // email client, from profile
"status": "completed", // status de la commande (sera systématiquement “completed” sur ce hook)
"created": "2021-01-15T09:02:16.000000Z", // date de création de la commande
"items": [
{
"id": 474784, // identifiant de l’item présent dans le panier
"price": 50, // prix de la formule commandé TTC
"tax": "0.000", // pourcentage TVA
"quantity": 1, // quantité de l’item en question dans le panier
"name": "Ma formule de box mensuelle", // nom de la formule commandé
"type": "App\\Plan", //
"orderable": { // paramètres relatifs a la formule commandée
"id": 1062, // identifiant de la formule choisie par le client
"uuid": "formule-box-mensuelle", // uuid de la formule choisie par le client (recoupe avec un export des commande par ex)
"name": "Ma formule de box mensuelle", // nom de la formule
"interval": "month", // interval choisit dans les paramètres de la formule
"interval_count": 1, // nombre d’intervals (parametre formule)
"start_billing_day": 1, // from param formule
"close_billing_day": 10, // from param formule
"short_name": null, // from param formule
"more": null, // from param formule
"active": true, // from param formule
"tenant_id": 82, // from param formule
"created_at": "2020-11-25T17:15:59.000000Z", // date de création de la formule dans l’admin
"updated_at": "2020-11-25T17:39:32.000000Z", // dernière date d'update de la formule dans l’admin
"deleted_at": null, // from param formule
"img": null, // from param formule
"shipped_count": 1, // nombre de ship par cycle d’engagement
"start_date": null, // from param formule
"best_value": "0", // from param formule
"alert": false, // from param formule
"need_auto_pause": false, // from param formule
"mass_shipping": true, // from param formule
"engaged": false, // from param formule
"engaged_interval": 0, // nombre de cycle d’engagements sur cette formule
"affilae": "5c34b7dbs8race63108b456c-5f1aa9bb0856337cd27ffc3a", // tagg affilae from param formule
"fixed_period": true, // from param formule
"category_id": null, // from param formule
"advanced_mod": null, // from param formule
"position": 449, // from param formule
"tax": 0.000, // pourcentage de TVA appliqué sur cette formule
"price": "50.00" // prix par cycle d’engagement formule hors taxe
},
"affilae": "5c34b7dbs8race63108b456c-5f6aa9bb0856337cd27ffc6a"
}
],
"shipping": "0.00", // prix facturé au client pour l'expédition lorsqu'elle est payante
"count": 1, // count de cet item dans le panier du client
"total_tax_paid": "0.00", // TVA value in euros
"total_discount_inc": "0.000", // montant de discount sur la vente
"total_paid": "50.000", // montant payé par le client TVA incluse
"total_shipping_paid": "0.000", // montant payé par le client pour l'expédition
"created_at": "2021-01-15T09:02:16.000000Z", // timestamp de la création de la commande
"coupon": [], // coupon
"subscription_uuid": "78be3696-cb96-4e2f-98c6-2a4951db6f1d", // UUID de l'abonnement
"comments": null, // commentaires de l'abo si présent
"revenue": "50.00", // revenus générés par cet abonnement (toujours = a total paid sur ce hook)
"refunded": "0.00", // montant remboursé sur la commande (toujours = a 0 sur ce hook)
"customerRevenue": "50.00", // revenus cumulatif de ce user
"customerRefund": "0.00", // refund cumulatif de ce user
"totalTransactionsSuccess": 1, // nombre total de transactions "completed" pour ce client
"subTransactionsSuccess": 1, // nombre total de transactions "completed" pour cet abonnement
"next_billing": "2021-03-01T00:00:00.000000Z", // date de prochain prélèvement de cet abonnement
"countTransactions": 1 // nombre total de transaction sur cette commande (sert a savoir quand une commande va se cloturer car nombre de transactions maximum excédé)
}Webhook de confirmation de commande (toutes les commandes, même en echec)
Celui-ci est déclenché à chaque tentative de paiement
{
"order_id": 230102, // see first hook
"user_id": 121888, // see first hook
"first_name": "NATHALIE", // see first hook
"last_name": "DUPONT", // see first hook
"phone": "0200000000", // see first hook
"email": "nathalie.dupont@outlook.fr", // see first hook
"status": "completed", // see first hook modulo le status n'est pas toujours completed car une transaction peut échouer sur une commande de reprélèvement
"created": "2021-01-15T01:03:03.000000Z", // see first hook
"items": [
{
"id": 474730, // see first hook
"price": 20, // see first hook
"tax": "0.000", // see first hook
"quantity": 1, // see first hook
"name": "Formule 1 mois", // see first hook
"type": "App\\Plan", // see first hook
"orderable": {
"id": 905, // see first hook
"uuid": "ma-box-formule-1-mois", // see first hook
"name": "Formule 1 mois", // see first hook
"interval": "month", // see first hook
"interval_count": 1, // see first hook
"start_billing_day": 1, // see first hook
"close_billing_day": 10, // see first hook
"short_name": null, // see first hook
"more": "Ma formule de box 1 mois", // see first hook
"active": false, // see first hook
"tenant_id": 82, // see first hook
"created_at": "2020-10-07T13:52:31.000000Z", // see first hook
"updated_at": "2020-11-30T08:39:15.000000Z", // see first hook
"deleted_at": null, // see first hook
"img": null, // see first hook
"shipped_count": 1, // see first hook
"start_date": null, // see first hook
"best_value": "0", // see first hook
"alert": false, // see first hook
"need_auto_pause": false, // see first hook
"mass_shipping": true, // see first hook
"engaged": false, // see first hook
"engaged_interval": 1, // see first hook
"affilae": null, // see first hook
"fixed_period": true, // see first hook
"category_id": null, // see first hook
"advanced_mod": null, // see first hook
"position": 331, // see first hook
"tax": 0.000, // see first hook
"price": "20.000" // see first hook
},
"affilae": null
}
],
"shipping": "0.00", // see first hook
"count": 1, // see first hook
"total_tax_paid": "0.000", // see first hook
"total_discount_inc": "20.000", // see first hook
"total_paid": "0.000", // see first hook
"total_shipping_paid": "0.000", // see first hook
"created_at": "2021-01-15T01:03:03.000000Z", // see first hook
"coupon": {
"id": 43768, // ID du coupon
"uuid": "MONCOUPON1MOIS", // nom du coupon
"plans": null, // see first hook
"price": "20.00", // montant du coupon
"percent_off": null, // pourcentage de réduction accordé (si coupon en pourcentage de réduction)6:42 PM 1/15/20216:42 PM 1/15/20216:42 PM 1/15/2021
"currency": null, // devise du coupon
"duration": "repeating", // parametre definit au niveau du coup (se répète ou one off)
"redeem_by": 1626350400, // ?
"display_amount": "20,00€", // valeur affichée du coupon
"display_percent": null // pourcentage affiché du coupon, lorsque le coupon fonctionne en pourcentage
},
"subscription_uuid": "bdda3255-b2f8-459b-adeb-75fe533fb579", // UUID de l'abonnement
"comments": null, // commentaires sur l'abonnement lorsqu'il y en a
"revenue": "0.00", // revenus cumulatifs de l'abonnement (somme des montants des transactions)
"refunded": "0.00", // refund cumulatifs effectués sur l'abonnement
"customerRevenue": "0.00", // revenus cumulatifs de ce user (client)
"customerRefund": "0.00", // refund cumulatifs de ce user (client)
"totalTransactionsSuccess": 3, // nombre de transactions "completed" sur ce user (client)
"subTransactionsSuccess": 3, // nombre de transactions "completed" sur cet abonnement
"next_billing": "2021-03-01T23:59:59.000000Z", // prochaine date de prélèvement (parametre présent sur l'abonnement)
"countTransactions": 1 // nombre de transactions sur cette commande (permet de savoir lorsqu'une commande va se cloturer pour cause de nombre de transaction)
}Webhook de mise en pause d'un abonnement
{
"id": 66641, // ID de la ressource abonnement
"uuid": "e5e00564-9cc8-402a-ba1e-6c69ff519c37", // UUID de l'abonnement
"plan": {
"id": 1057, // ID de la formule
"uuid": "ma-formule-3-mois", // UUID de la formule
"name": "Formule 3 Mois", // nom commercial de la formule
"short_name": null, // short name de la formule (si il y en a un)
"more": null, // from param formule
"image": "https://s4.eu-image-1.amazonaws.com/boxraiser/", // from param formule
"start_at": null, // from param formule
"price": 30, // from param formule
"category": null, // from param formule
"tax": 0.000, // pourcentage TVA from param formule
"addons": [], // addons selectionnés par le client (si il y en a)
"interval": "month", // from param formule
"interval_count": 3, // from param formule
"shipped_count": 3, // from param formule
"advanced_mod": null, // from param formule
"position": 444, // from param formule
"engaged_interval": 0, // from param formule
"engaged": false // from param formule
},
"address": {
"id": 96909, // ID de l'adresse du client
"address": "35 rue JEAN JAURES", // champs adresse du client
"address1": "", // see above
"postcode": "75000", // zip code de l'adresse du client utilisée pour cet abo
"city": "PARIS", // champs "ville" de l'adresse du client utilisée pour cet abonnement
"phone": "0600008888", // champs phone du profil client
"first_name": "MARIE", // champs prénom du profil client
"last_name": "THOMAS", // champs nom de famille du profil client
"country": {
"id": 2, // ID country de l'adresse utilisée pour cet abo
"name": "France Métropolitaine", // nom du pays de l'adresse du profil client utilisée pour cet abonnement
"alphaCode": "FR" // alpha code country from user profile pour cet abo
}
},
"transporter": {
"id": 381, // ID du transporter utilisé pour cet abonnement
"countries": [
{
"id": 2, // ID country de l'adresse utilisée pour cet abo (doit etre disponible pour ce transporteur pour qu'il puisse etre selectionné par le client)
"name": "France Métropolitaine" // nom pays de l'adresse utilisée pour cet abo (doit etre disponible pour ce transporteur pour qu'il puisse etre selectionné par le client)
}
],
"plan_blacklisted": [ // tous les "plans blacklisted" sont les formules bannies pour ce transporteur au niveau de l'admin
{
"id": 895,
"name": "1 Mois"
},
{
"id": 894,
"name": "2 Mois"
},
{
"id": 893,
"name": "3 Mois"
},
{
"id": 892,
"name": "4 Mois"
},
{
"id": 891,
"name": "6 Mois"
},
{
"id": 890,
"name": "8 Mois"
},
{
"id": 849,
"name": "1 mois"
},
{
"id": 934,
"name": "1 mois Aboone"
},
{
"id": 850,
"name": "2 mois"
},
{
"id": 935,
"name": "2 mois Abonne"
},
{
"id": 936,
"name": "3 mois Abonne"
},
{
"id": 937,
"name": "4 mois Abonne"
},
{
"id": 1063,
"name": "Complet 1 Mois"
},
{
"id": 1064,
"name": "Complet 2 Mois"
},
{
"id": 1065,
"name": "Complet 3 Mois"
},
{
"id": 1066,
"name": "Complet 4 Mois"
},
{
"id": 1067,
"name": "Complet 5 Mois"
},
{
"id": 1068,
"name": "Complet 6 Mois"
},
{
"id": 1069,
"name": "Complet 7 Mois"
},
{
"id": 1070,
"name": "Complet 8 Mois"
},
{
"id": 901,
"name": "Essentiel 1 mois"
},
{
"id": 902,
"name": "Essentiel 2 mois"
},
{
"id": 903,
"name": "Essentiel 3 mois"
},
{
"id": 904,
"name": "Essentiel 4 mois"
},
{
"id": 905,
"name": "Essentiel 6 mois"
},
{
"id": 906,
"name": "Essentiel 8 mois"
},
{
"id": 1131,
"name": "Complet 1 mois et plus"
},
{
"id": 1132,
"name": "Complet 2 mois et plus"
}
],
"name": "Livraison à domicile", // nom affiché du transporteur au niveau du checkout
"description": "1 livraisons par mois", // description du transporteur affiché au niveau du mode de livraison sur le checkout
"price": 0, // prix facturé au client pour le transport par box pour ce transporteur
"gift": false, // from param transporteur
"active": true, // param transporteur
"shipped_count": 1, // nombre d'expédition par cycle d'engagement pour ce transporteur (non administrable directement, demande de modif a effectuer auprès du service BoxRaiser)
"type": "subs", // from param transporteur
"relayOptions": null // from param transporteur
},
"declinaison": { // la partie declinaison représente les questions de profil posées lors du checkout
"id": 139740,
"attribute": {
"id": 47,
"name": "Votre Profil"
},
"values": [
{
"id": 283650,
"name": null,
"property": {
"id": 133,
"name": "Votre sexe",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 563,
"value": "Femme"
}
},
{
"id": 283651,
"name": null,
"property": {
"id": 134,
"name": "Quel est votre âge ?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 567,
"value": "Entre 35 et 45 ans"
}
},
{
"id": 283652,
"name": null,
"property": {
"id": 135,
"name": "Quel est votre taille de vêtements ?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 572,
"value": "L"
}
}
]
},
"created_at": "2020-12-08T17:52:44.000000Z", // date de création de l'UUID de l'abonnement en question (donc date de souscription du client a cette formule)
"end_date": "2021-02-01T00:00:00.000000Z", // date de fin de la commande en cours
"engaged_date": "2021-11-08T23:59:59.000000Z", // date de fin de l'engagement (définit par le nombre de cycle d'engagements de la formule)
"auto_pause_at": "2021-11-08T23:59:59.000000Z", // date d'auto pause de l'abonnement (définit par le nombre de cycle d'engagements de la formule)
"start_date": "2020-12-08T00:00:00.000000Z", // date de début de la souscription
"active": false, // paramètre abonnement (l'abonnement est-il actif)
"paused": false, // paramètre abonnement (l'abonnement a-t-il été mi en pause)
"next_billing": null, // date de prochain prélèvement de l'abonnement
"is_auto": false, // la mise en pause est-elle manuelle (stop par service client suite a requete client) ou automatique (fin naturelle de l'abonnement)
"revenue": "50.00", // revenu cumulatif de l'abonnement
"refunded": "0.00", // refunds cumulatifs de l'abonnement
"customerRevenue": "50.00", // revenus cumulatif de ce client
"customerRefund": "0.00", // refund cumulatifs poyur ce client
"totalTransactionsSuccess": 3, // nombre total de transaction "completed" sur ce client
"subTransactionsSuccess": 2, // nombre total de transactions "completed" sur cet abonnement
"has_active_subscription": false // le client a-t-il un abonnement actif
}Webhook de modification d'un abonnement (profil, transporteur, adresse)
{
"id": 118147, // ID client
"email": "cedricyoung@gmail.com", // email (a jour si il a été modifié) du client
"uuid": "549c8710-1a41-4cc2-ba28-607ebace2e63", // UUID du user
"refp": "https://winebox.fr/subscribe?refp=4f8e62c5-24c2-4208-ae62-4f771ae502ce", // referrer de la modification du profil
"can_void_with_coupon": true, // from user profile
"has_active_subscription": true, // ce user a-t-il un abonnement actif
"info": null, // from user profile
"addresses": [ // tous les paramètres relatifs aux différentes adresses de ce profil user
{
"id": 89278,
"address": "321 RUE JEAN MOULIN",
"address1": "",
"postcode": "75000",
"city": "PARIS",
"phone": "0610000000",
"first_name": "CEDRIC",
"last_name": "YOUN",
"country": {
"id": 2,
"name": "France Métropolitaine",
"alphaCode": "FR"
}
},
{
"id": 89279,
"address": "321 RUE JEAN MOULIN",
"address1": "",
"postcode": "75000",
"city": "PARIS",
"phone": "0610000000",
"first_name": "CEDRIC",
"last_name": "YOUN",
"country": {
"id": 2,
"name": "France Métropolitaine",
"alphaCode": "FR"
}
}
],
"profiles": [ // tous ces paramètres sont issus des champs de question de profil présente sur le check out
{
"id": 124540,
"attribute": {
"id": 47,
"name": "Votre Profil"
},
"values": [
{
"id": 259955, // QUESTION 1
"name": null,
"property": {
"id": 133,
"name": "Votre sexe",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 563,
"value": "Homme"
}
},
{
"id": 259956, // QUESTION 2
"name": null,
"property": {
"id": 134,
"name": "Quel est votre âge ?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 567,
"value": "Entre 35 et 45 ans"
}
},
{
"id": 259957, // QUESTION 3
"name": null,
"property": {
"id": 135,
"name": "Quelle est votre taille de vêtement ?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 573,
"value": "L"
}
}
]
}
],
"customerRevenue": "500.00", // revenus cumulatifs générés par ce user (somme des transactions "completed" TTC)
"customerRefund": "0.00", // refunds cumulatifs de ce user
"totalTransactionsSuccess": 3 // nombre total de transactions "completed" sur ce user
}Mis à jour le : 14/02/2023
Merci !