Loop Webhooks

Webhooks are a powerful tool that enables you to keep track of the subscription events occurring in the Loop system.

This article details the use of Webhooks with Loop and how you can leverage the same for your store.


How can Webhooks help?

Webhooks help stay in sync with the activities that matter most to you and automate actions based on those events. By subscribing to webhooks, you can receive notifications about specific events and use the data payload from the event to trigger custom logic. Overall, webhooks provide a reliable and efficient way to integrate with the Loop system and streamline your workflow.


How to respond to a Webhook ?

In order to confirm the receipt of data through your webhook, it is important to send a response with a status code in the 200 range, indicating success. If the response falls outside this range, it will signal that the webhook was not received.

Our system has been designed to include a 5-second time-out period for all webhook requests. If a response is not received within this timeframe, the request is considered to have failed.

To ensure that webhook requests are properly processed, our system will automatically retry failed requests over the next 48 hours. However, if a request continues to fail during each retry attempt, our system will take appropriate action and delete the webhook request.

By implementing these measures, we aim to provide a reliable and efficient webhook service that minimizes any potential disruptions to our client's operations.


What are Webhook attributes / headers?

Attributes and headers are two important components of a webhook payload. Attributes are key-value pairs that provide additional information about the event that triggered the webhook.

Following are the Webhook attributes for Loop.

id Unique numeric identifier for the webhook.
address The URI where the webhook should send the POST request when the event occurs.
topic The event that will trigger the webhook.
version The version of the API used to populate the body of the webhook.

Headers, on the other hand, are pieces of information sent along with the payload to provide additional context or instructions for how the payload should be processed.

Following are the Webhook headers for Loop.

X-Loop-Webhook-Id the unique id to identify duplicate entries
X-Loop-Webhook-Api-Version api version of the payload/webhook
X-Loop-Webhook-Topic Topic of the webhook eg: 'subscription/cancelled'
X-Loop-Webhook-Created-At Date time string when the event was created (remains same in every retry)
X-Loop-Webhook-Delivery-At date time string when the webhook is being delivered (also can be referred to as the time when it was retried)
X-Loop-Webhook-Retry-Count Number of retries/tries done

Webhooks that are currently supported

Webhook can be created in Loop for the following topics from object types - "Subscription" and "Order".

Object Topics
Subscription

subscription/created

subscription/paused

subscription/resumed

subscription/cancelled

subscription/reactivated

subscription/expired

Order

order/upcoming

order/processed

order/partiallyProcessed

order/outOfStock

order/skipped


List Webhook Topics

You can list your Webhook topics here

Sample response :

{
  "success": true,
  "message": "Fetched available topics",
  "data": [
    "subscription/created",
    "subscription/paused",
    "subscription/cancelled",
    "subscription/resumed",
    "subscription/reactivated",
    "subscription/expired"
  ]
}

How to subscribe / unsubscribe Webhook ?

  • How to subscribe to Webhooks?

You can subscribe to a webhook subscription by specifying both an address and a topic.

Click on the image for more details.

Sample response of Subscribe Webhook :

{
  "success": true,
  "message": "Successfully subscribed to the topic",
  "data": {
    "uuid": "533690245e3d47a683463304bf319136",
    "topic": "subscription/cancelled",
    "status": "ACTIVE",
    "version": "2022-10",
    "myshopifyDomain": "aug26-v2release.myshopify.com"
  }
}
  • How to unsubscribe from a Webhook?

You can unsubscribe from a webhook subscription using the Loop webhook subscription id.

Click on the image for more details

Sample response of Unsubscribe Webhook :

{
  "success": true,
  "message": "Successfully unsubscribed from the topic",
  "data": {}
}

Type of Webhooks and their payloads

  • Subscription Webhooks

The following Webhooks are available for subscriptions

Topic Description
subscription/created Triggered when a new subscription is created in Loop.
subscription/paused Triggered when a subscription is paused in Loop.
subscription/resumed Triggered when a subscription is resumed in Loop.
subscription/cancelled Triggered when a subscription is cancelled in Loop.
subscription/reactivated Triggered when a subscription is reactivated in Loop.
subscription/expired Triggered when a subscription is expired in Loop.
{
  "Payload":{
    "customer":{
      "shopifyId":5661127147673
      "email":"manas.oswal@loopwork.co",
      "phone":null,
      "firstName":"Manas",
      "lastName":"Oswal",
    },
    "shopifyId":2813788313,
    "originOrderShopifyId":null,
    "isPrepaid":false,
    "hasBundle":false,
    "note":null,
    "customAttributes":null,
    "createdAt":"2023-01-24T15:20:08.000Z",
    "nextOrderDate":null,
    "status":"CANCELLED",
    "cancelledAt":"2023-02-11T11:33:41.000Z",
    "pausedAt":null,
    "willAutoResume":false,
    "hasCustomPlan":false,
    "cancellationReason":"Already have enough stock",
    "cancellationComment":"",
    "completedOrdersCount":0,
    "currencyCode":"USD",
    "totalLineItemPrice":"202.50",
    "totalLineItemDiscountedPrice":"202.50",
    "deliveryPrice":"0.00",
    "discounts":[
       {
         "node":{
            "id":"gid://shopify/SubscriptionManualDiscount/...",
            "type": "CODE_DISCOUNT", 
            "title": "EarlyBird", 
            "value": {
               "percentage": 20
            }, 
            "targetType": "LINE_ITEM",
            "usageCount": 3, 
            "rejectionReason": "USAGE_LIMIT_REACHED",  
            "recurringCycleLimit": 1
          }
       }
    ],
    "lineItems":[
       {
         "shopifyId":"4bab2e11-b165-4dc5-b814-6ddaccf5ecaf",
         "name":"Gift Flowers - Small / Rose",
         "productTitle":"Gift Flowers",
         "variantTitle":"Small / Rose",
         "variantImage":"https://cdn.shopify.com/...",
         "sku":"",
         "productShopifyId":7287930814617,
         "variantShopifyId":41813627502745,
         "sellingPlanShopifyId":942538905,
         "sellingPlanName":"Deliver Every 2 months",
         "isOneTimeAdded":null,
         "isOneTimeRemoved":null,
         "price":"67.50",
         "quantity":1,
         "discountedPrice":"67.50",
         "basePrice":"75.00",
         "pricingPolicy":{
            "basePrice":{
            "amount":"75.0",
            "currencyCode":"USD"
            },
            "cycleDiscounts":[
               {
                  "afterCycle":0,
                  "computedPrice":{
                  "amount":"67.50",
                  "currencyCode":"USD"
                  },
                  "adjustmentType":"PERCENTAGE",
                  "adjustmentValue":{
                     "percentage":10
                  }
               }
            ]
          },
         "discountAllocations":[
            {
               "amount": {
                  "amount": "18.0", 
                  "currencyCode": "USD"
               },
               "discount": {
                  "id": "gid://shopify/SubscriptionManualDiscount/...",
                  "type": "CODE_DISCOUNT", 
                  "title": "freesub",
                  "value": {
                     "percentage": 100
                  },
                  "targetType": "LINE_ITEM",
                  "usageCount": 1,
                  "entitledLines": {
                     "all": true
                  },
                  "rejectionReason": null,
                  "recurringCycleLimit": null
               }
             }
          ],
         "bundleName":null,
         "bundleTransactionId":null,
         "requiresShipping":true,
         "taxable":true
       }
    ],
    "billingPolicy":{
       "intervalCount":1,
       "interval":"WEEK",
       "anchors":null,
       "minCycles":null,
       "maxCycles":null
    },
    "deliveryPolicy":{
      "intervalCount":1,
      "interval":"WEEK"
    },
    "shippingAddress":{
       "firstName":"Manas",
       "lastName":"Oswal",
       "company":null,
       "address1":"Pune",
       "address2":"First floor",
       "zip":"411002",
       "city":"Pune",
       "countryCode":"IN",
       "provinceCode":"MH"
    },
    "shippingLines":{
       "code":"Subscription shipping",
       "title":"Subscription shipping"
    }
  },
  "metaData":{
    "myshopifyDomain":"loop-subscriptions.myshopify.com"
  }
}
  • Order Webhooks

The Following Webhooks are available for Orders :

Topic Description
order/upcoming Triggered when an upcoming order is scheduled to process within the configured notification period
order/processed Triggered when an order is successfully processed in Loop
order/partiallyProcessed Triggered when an order is successfully processed but partially in Loop due to few items being out of stock
order/outOfStock Triggered when an order is skipped or delayed due to few or all items being out of stock
order/skipped Triggered when an order is skipped in Loop
{
  "Payload":{
    "customer":{...// all fields of customer payload
    },
    "Subscription":{... //all fields of subscription payload
    },
    "shopifyId":5661127147673,
    "scheduledAt":"2023-01-24T15:20:08.000Z",
    "status":"Paid",
    "currencyCode":"USD",
    "shippingPriceCurrencyCode":"USD",
    "totalLineItemsPrice":"200.00",
    "totalDiscountAmount":"50.00",
    "subtotalPrice":"150.00",
    "totalShippingPrice":"10.00",
    "totalTaxes":"10.00",
    "totalPrice":"170.00",
    "note":null,
    "customAttributes":null,
    "discountCodes":[
       {
          "code": "CUPID", 
          "type": "percentage",
          "amount": "4.39"
       }
    ],
    "lineItems":[ // only available in skipped and processed orders
       {
         "shopifyId":112121212,
         "name":"Gift Flowers - Small / Rose",
         "productTitle":"Gift Flowers",
         "variantTitle":"Small / Rose",
         "variantImage":"https://cdn.shopify.com/...",
         "sku":"gift001",
         "productShopifyId":7287930814617,
         "variantShopifyId":41813627502745,
         "price":"67.50",
         "quantity":1,
         "requiresShipping":true,
         "taxable":true,
         "properties": [{"name": "bundleId", "value": "2269f34745a347218821318b7e9119a8"}]
       }
    ],
    "skippedLineItems":[], //Sent in case of partially processed orders
    "shippingAddress":{ //only available in case of processed order
       "name":"Manas Oswal",
       "phone":null,
       "company":null,
       "address1":"Pune",
       "address2":"First floor",
       "zip":"411002",
       "city":"Pune",
       "provinceCode":"MH"
       "countryCode":"IN",
    },
    "shippingLines":{ //only available in case of processed order
       "code":"Subscription shipping",
       "title":"Subscription shipping"
    }
  }
}

FAQs

Q: How will I know that incoming webhooks are sent from Loop?

A: Loop webhook headers will always begin with "X-Loop-Webhook-{{variable_name}}".


Q: Can I use regular HTTP for my webhooks connections?

A: No, you must use a secure HTTPS connection in order to connect to our webhooks.


Need help?

No need to fret. We’re here to jump in and help you out. Reach out to us at support@loopwork.co, or feel free to ping us on chat by clicking the suppoSubsrt beacon on the bottom right.

Thanks,

Loop Subscription Team

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.