Getting Started

Overview

Webhooks are a way for Loop to send updates to your application automatically. They work by sending an HTTP request to the URL of your choosing.

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:

• Return
• Return processing
• Label
• Restock
• Gift card
• Happy Returns shipment

Available Triggers

Trigger	trigger property in payloads	Description
Return updated	return.updated	A return was updated. This includes state changes such as open to closed, cancelled, or expired.
Return created	return.created	A new return was submitted in the customer returns portal.
Return closed	return.closed	A return’s state has been updated to closed.
Return processing failed	return.processing.failed	Queued return processing failed to complete.
Label created	label.created	A shipping label has been created.
Label updated	label.updated	A shipping label has been updated (for example, the return’s status has changed from new to in transit).
Restock requested	restock.requested	An item in the return has been restocked in Shopify.
Gift card requested	giftcard.requested	A gift card has been requested as part of an exchange.
Shipment processed	shipment.processed	A Happy Returns shipment has been processed by Loop.

Additive Changes

Loop may add new fields to webhook payloads at any time without prior notice. These changes are additive only: we do not change the meaning of existing fields, change field types, or remove fields. Build your integration so that unknown or extra fields in the payload do not cause failures (for example, avoid strict schema validation that rejects additional properties).

Responding to Webhooks

Your webhook endpoint should respond with a successful HTTP status code (e.g. 200 OK, 202 Accepted, or 204 No Content) within 10 seconds. If you do not respond within that duration, the webhook delivery is treated as a failure and will be queued to retry. If you have complex processing like database queries or external API calls that may exceed this timeout, return the response before processing.

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.

Webhooks from Loop have a policy of at least once delivery. This means in rare cases, the same webhook payload may be delivered more than once to your endpoint. Be sure to build your integration defensively to account for this possibility.

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 are included below.

Error code	Retryable	Explanation
403	No	Forbidden access, typically due to invalid credentials or permission issues.
500	Yes	Internal server error. While not always recoverable, retries might succeed if caused by temporary issues like resource contention.
400	No	Bad request, often caused by invalid payloads.
0	Yes	Network or connectivity issues resulting in an ambiguous failure. Retrying can address transient network instability.
404	No	Not found, likely due to a nonexistent resource.
405	No	Method not allowed, caused by incorrect HTTP method usage.
401	No	Unauthorized access, likely due to expired or invalid tokens.
503	Yes	Service unavailable, often due to temporary server downtime or overload. Retrying may succeed after a delay.
504	Yes	Gateway timeout, caused by upstream server delays. Retrying can succeed if the issue is temporary.
502	Yes	Bad gateway, usually due to temporary issues with upstream servers. Retrying may resolve the error.
422	No	Unprocessable entity, typically due to invalid payloads.
410	No	Gone, indicating the resource is permanently unavailable.
429	Yes	Too many requests, caused by rate limits. These are explicitly retryable after the Retry-After interval.