Webhooks
Webhooks
What are webhooks?
Let's take the example of your bank. When you make a withdrawal, the ATM checks the remaining balance on your account and outputs the amount you requested. Once this is done, your balance is updated. This change in balance triggers an action: an SMS is sent to you with the details of the withdrawal. This is how webhooks work.
A webhook allows you to trigger an action following an event. They are generally used to connect systems. It is the easiest way to get an alert when something happens in another system.
Webhooks are used for real-time notifications, so your system can be updated as soon as the event occurs.
Webhooks are HTTP callbacks that are user defined. They allow you to register a URL where the event data can be stored. Then you can do whatever you want with the data you retrieve and store from an event by triggering an action.
With webhooks you can, among other things:
Synchronize systems in real time
Send any type of notification
Process data the way you want
Create reports
...
How to set up a webhook?
Let's take an example: You want to store in an excel file the contacts of the people who placed an order on your site.
Prerequisite: You must create your account on Integromat.
Create a scenario** by selecting the Custom Webhook trigger.
Name the webhook**.
.png>)The webhook is listening** : Copy the url given by Integromat and keep this window open.
Fill in the url given by Integromat in the Ciklik application.
Click on Sites, then Edit.
In the Marketing parameters tab, add the keys and URL of the associated webhooks in the Webhooks field.
Place an order on your site to enable webhook listening** and data feedback for this scenario.
You can now build your scenario** to use the data received during an order and automatically carry out the actions of your choice.
Before creating an action, link the trigger to a router. This will allow you to trigger several actions during an order without having to set up everything again.
Now select the application you want to use for your action.
In our example, we want to collect the information in an excel sheet.
Create a blank file in your drive and give it the desired structure by defining the column values.
Then you have to connect to your google account.
Then enter the name of the google sheet in which the data selected from the list of values returned by the Ciklik application will be retrieved via the webhook when an order is created.
Confirm your scenario and activate it. You can test by placing a new order on your site. You will automatically find the values of the fields in your excel file.
Which events are available?
Here is the list of available events for webhooks from the Ciklik application:
| Key |
|---|
| subscription |
| updated_subscription |
| deleted_subscription |
| checkoutorder |
| updated_checkoutorder |
| checkouttransaction |
| updated_checkouttransaction |
| checkoutinvoice |
| address |
| updated_address |
| shippingbox |
| updated_shippingbox |
| deleted_shippingbox |
| user |
| upated\_user |
| optin |
| updated_optin |
For each of these keys, a scenario can be triggered with a webhook by entering its URL in the Webhooks field in the Marketing parameters tab of your site.
In the Webhooks section of the left-hand column, you will find details of the data sent via webhooks when the scenario has been successfully executed. This data is temporarily saved in the application.
.png>)For updates (updated), we find the list of changed fields and their new value in the "changed" table:
(1).png>)The URL for the management of abandoned shopping carts is filled in at the Url Webhook: Abandoned shopping carts field.
Webhook logs are accessible from the Webhooks section in the left column and are available for 20 days.
What information is reported?
Each code block below contains the information that is sent back via the webhooks, in the following format:
| Value | Example | Note |
|---|---|---|
| "cart\_id" | 1042077 | // Cart ID |
Webhook Abandoned Cart
javascript
"cart_id": 1042077, // Cart ID
"user_id": 133180, // ID of the user who generated this cart
"first_name": "JEANNE", // first name of the user who generated this cart (from user profile)
"last_name": "MOULIN", // last name of the user who generated this cart (from user profile)
"phone": "0604000000", // telephone of the user who generated this cart (from user profile)
"email": "jeannemoulin06@gmail.com", // email of the user who generated this cart (from user profile)
"created": "2021-01-17T21:05:47.000000Z", // timestamp of the cart creation
"item": "Box 3 months" // formula present in the cart
```
Webhook to create a new subscription
{
"order_id": 230129, // order ID
"user_id": 122312, // UUID user (customer)
"first_name": "ANNE", // first name customer (from profile)
"last_name": "DUPOND", // last name customer (from profile)
"phone": "0600000000", // telephone client, from checkout
"email": "annedupond@gmail.com", // email client, from profile
"status": "completed", // status of the order (will always be "completed" on this hook)
"created": "2021-01-15T09:02:16.000000Z", // order creation date
"items": [
{
"id": 474784, // identifier of the item in the cart
"price": 50, // price of the formula ordered including VAT
"tax": "0.000", // VAT percentage
"quantity": 1, // quantity of the item in the cart
"name": "My monthly box formula", //name of the ordered formula
"type": "App\\Plan", //
"orderable": { // parameters relative to the ordered formula
"id": 1062, // identifier of the formula chosen by the customer
"uuid": "monthly-box-formula", // uuid of the formula chosen by the customer (cross-referenced with an order export for example)
"name": "My monthly box formula", // name of the formula
"interval": "month", // interval chosen in the parameters of the formula
"interval_count": 1, // number of intervals (formula parameter)
"start_billing_day": 1, // from formula parameter
"close_billing_day": 10, // from param formula
"short_name": null, // from param formula
"more": null, // from param formula
"active": true, // from param formule
"tenant_id": 82, // from param formule
"created_at": "2020-11-25T17:15:59.000000Z", // creation date of the formula in the admin
"updated_at": "2020-11-25T17:39:32.000000Z", // last update date of the formula in the admin
"deleted_at": null, // from param formula
"img": null, // from param formule
"shipped_count": 1, // number of ships per commitment cycle
"start_date": null, // from param formula
"best_value": "0", // from param formula
"alert": false, // from param formule
"need_auto_pause": false, // from param formula
"mass_shipping": true, // from param formule
"engaged": false, // from param formula
"engaged_interval": 0, // number of engagement cycles on this formula
"affilae": "5c34b7dbs8race63108b456c-5f1aa9bb0856337cd27ffc3a", // tagg affilae from param formula
"fixed_period": true, // from param formula
"category_id": null, // from param formule
"advanced_mod": null, // from param formule
"position": 449, // from param formule
"tax": 0.000, // percentage of VAT applied on this formula
"price": "50.00" // price per commitment cycle formula excluding tax
},
"affilae": "5c34b7dbs8race63108b456c-5f6aa9bb0856337cd27ffc6a"
}
],
"shipping": "0.00", // price charged to the customer for shipping when it is paid
"count": 1, // count of this item in the customer's cart
"total_tax_paid": "0.00", // VAT value in euros
"total_discount_inc": "0.000", // discount amount on the sale
"total_paid": "50.000", // amount paid by customer including VAT
"total_shipping_paid": "0.000", // amount paid by customer for shipping
"created_at": "2021-01-15T09:02:16.000000Z", // timestamp of order creation
"coupon": [], // coupon
"subscription_uuid": "78be3696-cb96-4e2f-98c6-2a4951db6f1d", // UUID of the subscription
"comments": null, // comments of the subscription if present
"revenue": "50.00", // revenue generated by this subscription (always = a total paid on this hook)
"refunded": "0.00", // amount refunded on the order (always = a 0 on this hook)
"customerRevenue": "50.00", // cumulative revenue of this user
"customerRefund": "0.00", // cumulative refund of this user
"totalTransactionsSuccess": 1, // total number of completed transactions for this customer
"subTransactionsSuccess": 1, // total number of "completed" transactions for this subscription
"next_billing": "2021-03-01T00:00:00.000000Z", // next billing date for this subscription
"countTransactions": 1 // total number of transactions on this order (used to know when an order will be closed because the maximum number of transactions has been exceeded)
}Order confirmation webhook (all orders, even failed ones)
This one is triggered at each payment attempt
javascript
{
"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 the status is not always completed because a transaction can fail on a rework order
"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": "my-box-formula-1-month", // 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": "My 1 month box formula", // 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, // coupon ID
"uuid": "MONCOUPON1MOIS", // coupon name
"plans": null, // see first hook
"price": "20.00", // coupon amount
"percent_off": null, // percentage discount granted (if percentage discount coupon)6:42 PM 1/15/20216:42 PM 1/15/20216:42 PM 1/15/2021
"currency": null, // currency of coupon
"duration": "repeating", // parameter defined at the move level (repeats or one off)
"redeem_by": 1626350400, // ?
"display_amount": "20,00€", // displayed value of the coupon
"display_percent": null // displayed percentage of the coupon, when the coupon works in percent
},
"subscription_uuid": "bdda3255-b2f8-459b-adeb-75fe533fb579", // UUID of the subscription
"comments": null, // comments on the subscription when available
"revenue": "0.00", // cumulative revenue of the subscription (sum of transaction amounts)
"refunded": "0.00", // cumulative refunds made on the subscription
"customerRevenue": "0.00", // cumulative revenue of this user (customer)
"customerRefund": "0.00", // cumulative refunds of this user (customer)
"totalTransactionsSuccess": 3, // number of "completed" transactions on this user (customer)
"subTransactionsSuccess": 3, // number of "completed" transactions on this subscription
"next_billing": "2021-03-01T23:59:59.000000Z", // next debit date (parameter present on the subscription)
"countTransactions": 1 // number of transactions on this order (allows to know when an order will be closed because of the number of transactions)
}
```
Webhook to pause a subscription
{
"id": 66641, // ID of the subscription resource
"uuid": "e5e00564-9cc8-402a-ba1e-6c69ff519c37", // UUID of the subscription
"plan": {
"id": 1057, // Plan ID
"uuid": "my-plan-3-month", // UUID of the plan
"name": "Formula 3 Months", // business name of the formula
"short_name": null, // short name of the formula (if there is one)
"more": null, // from param formula
"image": "https://s4.eu-image-1.amazonaws.com/boxraiser/", // from param formula
"start_at": null, // from param formula
"price": 30, // from param formula
"category": null, // from param formula
"tax": 0.000, // percentage VAT from param formula
"addons": [], // addons selected by the customer (if any)
"interval": "month", // from param formula
"interval_count": 3, // from param formula
"shipped_count": 3, // from param formula
"advanced_mod": null, // from param formula
"position": 444, // from param formule
"engaged_interval": 0, // from param formule
"engaged": false // from param formula
},
"address": {
"id": 96909, // ID of the customer's address
"address": "35 rue JEAN JAURES", // customer address fields
"address1": "", // see above
"postcode": "75000", // zip code of the customer address used for this subscription
"city": "PARIS", // "city" fields of the customer address used for this subscription
"phone": "0600008888", // phone field of the customer profile
"first_name": "MARIE", // first name field of the customer profile
"last_name": "THOMAS", // last name field of the customer profile
"country": {
"id": 2, // country ID of the address used for this subscription
"name": "France Métropolitaine", // country name of the address used for this subscription
"alphaCode": "FR" // alpha code country from user profile for this subscription
}
},
"transport": {
"id": 381, // ID of the transporter used for this subscription
"countries": [
{
"id": 2, // country ID of the address used for this subscription (must be available for this carrier to be selected by the customer)
"name": "France Métropolitaine" // country name of the address used for this subscription (must be available for this carrier to be selected by the customer)
}
],
"plan_blacklisted": [ // all "blacklisted plans" are the banned plans for this carrier at admin level
{
"id": 895,
"name": "1 Month"
},
{
"id": 894,
"name": "2 Months"
},
{
"id": 893,
"name": "3 Months"
},
{
"id": 892,
"name": "4 Months"
},
{
"id": 891,
"name": "6 Months"
},
{
"id": 890,
"name": "8 Months"
},
{
"id": 849,
"name": "1 Month"
},
{
"id": 934,
"name": "1 month Aboone"
},
{
"id": 850,
"name": "2 months"
},
{
"id": 935,
"name": "2 months Subscriber"
},
{
"id": 936,
"name": "3 months Subscriber"
},
{
"id": 937,
"name": "4 months Subscriber"
},
{
"id": 1063,
"name": "Full 1 Month"
},
{
"id": 1064,
"name": "Complete 2 Months"
},
{
"id": 1065,
"name": "Complete 3 Months"
},
{
"id": 1066,
"name": "Complete 4 Months"
},
{
"id": 1067,
"name": "Complete 5 Months"
},
{
"id": 1068,
"name": "Complete 6 Months"
},
{
"id": 1069,
"name": "Complete 7 Months"
},
{
"id": 1070,
"name": "Complete 8 Months"
},
{
"id": 901,
"name": "Essential 1 Month"
},
{
"id": 902,
"name": "Essential 2 months"
},
{
"id": 903,
"name": "Essential 3 months"
},
{
"id": 904,
"name": "Essential 4 months"
},
{
"id": 905,
"name": "Essential 6 months"
},
{
"id": 906,
"name": "Essential 8 months"
},
{
"id": 1131,
"name": "Full 1 month and up"
},
{
"id": 1132,
"name": "Full 2 months and more"
}
],
"name": "Home delivery", // name of the carrier displayed on the checkout
"description": "1 deliveries per month", // description of the carrier displayed in the delivery mode on the checkout
"price": 0, // price charged to the customer for the transport by box for this carrier
"gift": false, // from param carrier
"active": true, // param carrier
"shipped_count": 1, // number of shipments per commitment cycle for this carrier (not directly manageable, change request to be made to the BoxRaiser service)
"type": "subs", // from param carrier
"relayOptions": null // from param carrier
},
"declination": { // the declination part represents the profile questions asked during the checkout
"id": 139740,
"attribute": {
"id": 47,
"name": "Your Profile"
},
"values": [
{
"id": 283650,
"name": null,
"property": {
"id": 133,
"name": "Your gender",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 563,
"value": "Female"
}
},
{
"id": 283651,
"name": null,
"property": {
"id": 134,
"name": "How old are you?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 567,
"value": "Between 35 and 45 years old"
}
},
{
"id": 283652,
"name": null,
"property": {
"id": 135,
"name": "what is your clothing size?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 572,
"value": "L"
}
}
]
},
"created_at": "2020-12-08T17:52:44.000000Z", // date of creation of the UUID of the subscription in question (thus date of subscription of the customer to this formula)
"end_date": "2021-02-01T00:00:00.000000Z", // end date of the current order
"engaged_date": "2021-11-08T23:59:59.000000Z", // end date of the engagement (defined by the number of engagement cycle of the formula)
"auto_pause_at": "2021-11-08T23:59:59.000000Z", // date of auto pause of the subscription (defined by the number of commitment cycle of the formula)
"start_date": "2020-12-08T00:00:00.000000Z", // subscription start date
"active": false, // subscription parameter (is the subscription active)
"paused": false, // subscription parameter (has the subscription been paused)
"next_billing": null, // next date of the subscription
"is_auto": false, // is the pause manual (stop by customer service after a customer request) or automatic (natural end of the subscription)
"revenue": "50.00", // cumulative revenue of the subscription
"refunded": "0.00", // cumulative subscription refunds
"customerRevenue": "50.00", // cumulative revenue of this customer
"customerRefund": "0.00", // cumulative refunds for this customer
"totalTransactionsSuccess": "3", // total number of completed transactions for this customer
"subTransactionsSuccess": 2, // total number of completed transactions on this subscription
"has_active_subscription": false // does the customer have an active subscription
}Webhook to modify a subscription (profile, carrier, address)
javascript
{
"id": 118147, // customer ID
"email": "cedricyoung@gmail.com", // customer email (updated if modified)
"uuid": "549c8710-1a41-4cc2-ba28-607ebace2e63", // UUID of user
"refp": "https://winebox.fr/subscribe?refp=4f8e62c5-24c2-4208-ae62-4f771ae502ce", // referrer of the profile modification
"can_void_with_coupon": true, // from user profile
"has_active_subscription": true, // does this user have an active subscription
"info": null, // from user profile
"addresses": [ // all parameters related to the different addresses of this user profile
{
"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": [ // all these parameters come from the profile question fields present on the check out
{
"id": 124540,
"attribute": {
"id": 47,
"name": "Your Profile"
},
"values": [
{
"id": 259955, // QUESTION 1
"name": null,
"property": {
"id": 133,
"name": "Your gender",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 563,
"value": "Male"
}
},
{
"id": 259956, // QUESTION 2
"name": null,
"property": {
"id": 134,
"name": "How old are you?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 567,
"value": "Between 35 and 45 years old"
}
},
{
"id": 259957, // QUESTION 3
"name": null,
"property": {
"id": 135,
"name": "What is your clothing size?",
"type": "list",
"predefined": true
},
"value": null,
"propValue": {
"id": 573,
"value": "L"
}
}
]
}
],
"customerRevenue": "500.00", // cumulative revenue generated by this user (sum of "completed" transactions including VAT)
"customerRefund": "0.00", // cumulative refunds from this user
"totalTransactionsSuccess": 3 // total number of "completed" transactions for this user
}
```
Updated on: 24/01/2023
Thank you!