Webhooks are HTTP callbacks processed and sent by Loop to a pre-defined URL. They allow your application to receive information from Loop without having to reach out to Loop with an API call. Each webhook has a topic, which defines the information payload, and a trigger, which determines the event which triggers the request to be sent from Loop.
Loop offers five webhook topics and eight triggers.
Topics:
- Return
- Label
- Restock
- Giftcard
- Happy Returns shipment
Triggers:
- Return updated: A return has been updated (e.g. state has changed from
opentoclosed). - Return created: A new return was submitted in the Returns Portal.
- Return closed: A return's state has been updated to
closed. - Label created: A shipping label has been created via EasyPost (or other shipping service) .
- Label updated: A shipping label has been updated (e.g. status has changed from
newtoin transit). - Restock requested: An item in the return has been restocked in Shopify.
- Giftcard requested: A gift card has been requested as part of an exchange.
- Shipment processed: A Happy Returns shipment has been processed.
To set up webhooks, go to the Developers page in the Loop admin or your sandbox account. There, you can create a webhook, select a topic and trigger for the webhook, and define the URL the payload will be sent to.
Webhooks can have one of the following statuses:
- Inactive: Manually deactivated by a user
- Active: Webhook is operating normally
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. |
Loop webhook tips
Webhook topics and triggers can be combined to suit your desired outcome. There are also certain combinations that will not yield results. (For example, If you set up a webhook with a topic of Label and a trigger of Return create, there will be no payload available, as a return needs to be created before a label is generated.)
If you wish to see the information payload of a webhook before incorporating the webhook into your code, the webpage webhook.site provides you with a URL to use in the webhook and display the information you receive on their page, allowing you to examine the JSON structure of the payload when the webhook is fired (even as a test). Later on, you can change the webhook URL for production use.
If you need additional support regarding webhooks, please contact Loop's support team.