​
Overview

Webhooks are a way for Loop to send updates to your application automatically. They work by sending an HTTP request to a URL you choose ahead of time. Each webhook has a topic, which defines the type of information included in the message, and a trigger, which is the event in Loop that causes the webhook to be sent. This means your application can get real-time updates from Loop without needing to constantly check for new information. Webhooks make it easier to keep everything in sync and up to date.

​
Topics & Triggers

A webhook’s topic determines the type of information included in the payload that Loop sends to your application. Each topic is tailored to specific data, such as labels or returns, ensuring that you only receive the information relevant to your needs.
Not all topics will yield results for every trigger. For example, if you use the label topic with a return created trigger, the payload might be empty because the label isn’t generated yet. Make sure topics match trigger events to get meaningful data.

​
Available Topics

Topics:

​
Available Triggers

Triggertrigger property in payloadsDescription
Return updatedreturn.updatedA return has been updated (for example, the return state has changed from open to closed).
Return createdreturn.createdA new return was submitted in the customer returns portal.
Return closedreturn.closedA return’s state has been updated to closed.
Label createdlabel.createdA shipping label has been created.
Label updatedlabel.updatedA shipping label has been updated (for example, the return’s status has changed from new to in transit).
Restock requestedrestock.requestedAn item in the return has been restocked in Shopify.
Gift card requestedgiftcard.requestedA gift card has been requested as part of an exchange.
Shipment processedshipment.processedA Happy Returns shipment has been processed by Loop.

​
Testing Webhooks

To preview the payload of a webhook before integrating it into your code, you can use webhook.site. This tool provides a temporary URL you can set as the webhook destination. When the webhook is triggered, it displays the received payload, allowing you to inspect its JSON structure, even for test events. Once you’re ready, you can update the webhook URL for production use. For further assistance with webhooks, feel free to reach out to Loop’s support team.

​
Webhook Errors and Retries

In the event of a webhook error, one of the following error codes is typically sent. Depending on the type of error, failed webhooks automatically retry after a short period of time. Retries are attempted five times (for a total of six attempts) using exponential backoff with jitter. We respect the retry-after header for values up to 30 minutes. For higher values, we fail the webhook. The values above are set by config and subject to change. Details on each error code and whether they permit retries is included below.
Error codeRetryableExplanation
403NoForbidden access, typically due to invalid credentials or permission issues.
500YesInternal server error. While not always recoverable, retries might succeed if caused by temporary issues like resource contention.
400NoBad request, often caused by invalid payloads.
0YesNetwork or connectivity issues resulting in an ambiguous failure. Retrying can address transient network instability.
404NoNot found, likely due to a nonexistent resource.
405NoMethod not allowed, caused by incorrect HTTP method usage.
401NoUnauthorized access, likely due to expired or invalid tokens.
503YesService unavailable, often due to temporary server downtime or overload. Retrying may succeed after a delay.
504YesGateway timeout, caused by upstream server delays. Retrying can succeed if the issue is temporary.
502YesBad gateway, usually due to temporary issues with upstream servers. Retrying may resolve the error.
422NoUnprocessable entity, typically due to invalid payloads.
410NoGone, indicating the resource is permanently unavailable.
429YesToo many requests, caused by rate limits. These are explicitly retryable after the Retry-After interval.