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:
Available Triggers
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.
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.
