Getting Started
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.
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
| Trigger | trigger property in payloads | Description |
|---|---|---|
| Return updated | return.updated | A return has been updated (for example, the return state has changed from open to closed. |
| 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. |
| 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. |
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 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. |