Ordergroove offers a webhook system designed to facilitate seamless integration between our platform and client systems. This system transmits HTTP requests in response to specific modifying events occurring within the Ordergroove ecosystem. Some examples of such events are: an order reminder being sent to a customer, a canceled subscription, a new subscription created, among others. The webhook system's primary function is to ensure that clients are informed of these critical events, thereby enabling real-time data synchronization.
Clients have the flexibility to configure webhook routes according to their specific requirements. This includes the ability to select only those events that are pertinent to their operational needs and to customize the content of the outgoing requests. Such configurability ensures that the webhooks provide targeted and relevant information, avoiding unnecessary data transmission.
The utilization of Ordergroove's webhook system is instrumental in bridging the gap between the management of subscription data on our platform and the execution of subsequent processes within external systems. This integration is vital for enhancing customer experience and improving operational efficiency.
This documentation aims to provide comprehensive guidance on the setup, configuration, and best practices for leveraging Ordergroove's webhook system to its fullest potential.
For more information, authentication, payloads and more see Installing Webhooks 2.0 under Program Data.
What's the difference between 1.0 and 2.0?
Webhooks 2.0 is an enhanced version of Ordergroove’s current webhook offering. It allows a merchant to combine multiple data points into a single webhook response.
Ordergroove’s webhook version prior to 2.0 would require additional API calls to get additional information such as shipping address, subscription extra_data, or customer information. Now, you can configure which data points are valuable to receive in a single webhook notification!
Setup
Accessing the webhooks configurator
We'll be using the webhooks configuration interface. You can access it through your Ordergroove Admin:
- Log in to Ordergroove.
- Go to Developers on the top toolbar, and select Webhooks.
- Click + CREATE WEBHOOK to begin
- Select which events you want to receive webhook notification for and any additional webhooks data that you want included in the payload. For example, an order event will only contain order level information. If you select to add subscription and item level data, that will also be sent in the payload of the webhook.
Note
Order and Item level data cannot be added to subscriber or subscription events at this time. Adding subscription level data to order and item level events is supported in the Alpha of webhooks 2.0.
Payload Structure
The additional webhooks data selected during configuration will be sent in the snapshot object within the payload. See example:
{
"id": "mmmm4444nnnn3333pppp",
"type": "subscriber.create",
"created": 1622589211,
"data": {
"object": {
"type": "subscriber",
// ... (existing subscriber data)
},
"snapshot": {
"customer": {},
"subscriptions": [...],
"orders": [...],
"items": [...],
"products": [...],
"addresses": [...],
"payments": [...]
}
}
}
The Snapshot Object
This object will include the additional selected data during configuration of the webhook. The customer object within snapshot will be a single customer since all webhooks can only be tied to one customer. The subscriptions, orders, items, addresses, payments, and product objects will always be a list object even if there is only one object within the list. Example:
"snapshot": {
"customer": {
"id": "00026001",
"public_id": "c4cd7f86ccc411e8ada3bc764e101db1",
"first_name": "Nathan",
"last_name": "Torres",
"address": "75 Broad St Fl 23",
"address2": null,
"city": "New York",
"state_province_code": "NY",
"zip_postal_code": "10004-2487",
"phone": "3154055372",
"fax": null,
"country_code": "US",
"live": true,
"created": "2018-10-10 14:43:32",
"token_id": null,
"store_public_id": null
},
"subscriptions": [{
"customer": "00026001",
"merchant": "ac4f7938383a11e89ecbbc764e1107f2",
"product": "0070067689",
"payment": "443ddf72094711e9a5afbc764e1043b0",
"shipping_address": "394aee16d61611e88b4abc764e1043b0",
"offer": "a748aa648ac811e8af3bbc764e106cf4",
"subscription_type": "replenishment",
"components": [],
"extra_data": {},
"public_id": "0ff0f88accc511e8b6c0bc764e106cf4",
"product_attribute": null,
"quantity": 4,
"price": null,
"frequency_days": 120,
"reminder_days": 10,
"every": 4,
"every_period": 3,
"start_date": "2018-12-27",
"cancelled": null,
"cancel_reason": null,
"cancel_reason_code": null,
"iteration": null,
"sequence": null,
"session_id": "ac4f7938383a11e89ecbbc764e1107f2.896371.1539022086",
"merchant_order_id": "2906548",
"customer_rep": null,
"club": null,
"created": "2018-10-10 14:45:38",
"updated": "2019-01-17 12:09:23",
"live": true
}],
"orders": [{
"merchant": "ac4f7938383a11e89ecbbc764e1107f2",
"customer": "00026001",
"payment": "070001bc02fd11e99542bc764e1043b0",
"shipping_address": "66c25cd0564011e9abc5bc764e107990",
"public_id": "c4e05d04ccc411e8ada3bc764e101db1",
"sub_total": "22.90",
"tax_total": "0.00",
"shipping_total": "5.99",
"discount_total": "21.08",
"total": "28.89",
"created": "2018-10-10 14:43:32",
"place": "2019-06-06 12:08:37",
"cancelled": "2019-04-05 12:13:32",
"tries": 1,
"generic_error_count": 0,
"status": 1,
"type": 1,
"order_merchant_id": "",
"rejected_message": "",
"extra_data": "",
"locked": false,
"oos_free_shipping": false
}],
"items": [{
"order": "45c27952cd9211e8855abc764e106cf4",
"offer": null,
"subscription": "6199282ccd8f11e88267bc764e106cf4",
"product": "0070067698",
"components": [],
"quantity": 1,
"public_id": "45c39ceccd9211e8855abc764e106cf4",
"product_attribute": null,
"price": "79.99",
"extra_cost": "0.00",
"total_price": "35.99",
"one_time": false,
"frozen": false,
"first_placed": null
}],
"products": [{
"merchant": "ac4f7938383a11e89ecbbc764e1107f2",
"groups": [],
"name": "Wild Yam Root 405mg",
"price": "6.99",
"image_url": "https://staging-web-vitaminworld.demandware.net/on/demandware.static/-/Sites-vitaminworld-master/default/dwafa9ff17/images/2017/000030.jpg",
"detail_url": "https://staging-web-vitaminworld.demandware.net/s/vitaminworld_us/wild-yam-root-405mg-0070000030.html",
"external_product_id": "0070000030",
"sku": "0070000030",
"autoship_enabled": false,
"premier_enabled": 0,
"created": "2018-07-24 10:06:10",
"last_update": "2018-11-20 10:48:00",
"live": false,
"discontinued": false,
"offer_profile": null,
"extra_data": null,
"incentive_group": null,
"product_type": "standard",
"autoship_by_default": false,
"every": 2,
"every_period": 2
}],
"addresses": [{
"customer": "00026001",
"public_id": "c4cd7f86ccc411e8ada3bc764e101db1",
"label": null,
"first_name": "Nathan",
"last_name": "Torres",
"company_name": null,
"address": "75 Broad St Fl 23",
"address2": null,
"city": "New York",
"state_province_code": "NY",
"zip_postal_code": "10004-2487",
"phone": "3154055372",
"fax": null,
"country_code": "US",
"live": true,
"created": "2018-10-10 14:43:32",
"token_id": null,
"store_public_id": null
}],
"payments": [{
"customer": "00026001",
"billing_address": "c4cfc106ccc411e8ada3bc764e101db1",
"cc_number_ending": null,
"public_id": "c4d1d4e6ccc411e8ada3bc764e101db1",
"label": null,
"token_id": "5CA94EAA-AADE-4918-ABEE-8C8531411BAE",
"cc_holder": null,
"cc_type": 1,
"cc_exp_date": "02/2020",
"payment_method": "credit card",
"live": false,
"created": "2018-10-10 14:43:32",
"last_updated": "2018-10-10 14:43:32"
}]
}
Glossary
Ordergroove event object: Entity within Ordergroove on which an event can occur. The four possible entities are:
- Order
- Item
- Subscription
- Subscriber
Ordergroove webhook event: Payload representing an action taken by a customer, user, or system, which modifies an Ordergroove event object.
Target: The URL designated to receive the HTTP request body of an Ordergroove webhook event.
Webhook target: Alternative to “Target”.
Webhook route: A configuration unit in the Ordergroove system where the webhook target is specified and managed. This entity serves as the operational scope for various management activities, including halting webhook deliveries to the target, determining the specific events to be sent to the target, and other related actions.
Delivery: An Ordergroove webhook event bound to a specific route, representing an attempt to send an HTTP request to the configured target. Each delivery undergoes a series of statuses, reflecting its journey from initiation to completion. These statuses are determined by factors such as the successful transmission of the request to the target, the response received from the target, the need for request retries, and other relevant considerations. This progression of statuses provides insight into the lifecycle of each webhook event as it interacts with the target.