Getting started

​

Introduction

When data in our database changes, we capture the update and trigger a webhook to our customers. This approach keeps your data current without the need to poll our API.

Our webhooks are organized by entity and mirror the models in our API. For example, if you are interested in documents, you can subscribe to document-related webhooks like document.report.created or document.slides.deleted.

​

Managing and monitoring webhooks

To subscribe to webhooks, create a webhook subscription by adding an endpoint in the webhook section of the portal and selecting the events you want to receive. You can review dispatched webhooks, along with their payload data, timestamps, and status, directly in the portal.

​

Webhook behavior

​

Timeouts and retries

Each webhook request has a 10-second timeout and is retried four times on a fixed schedule:

• First retry: after 5 seconds
• Second retry: after 2 minutes
• Third retry: after 15 minutes
• Fourth retry: after 1 hour

If all attempts fail, the webhook is marked as failed and can be retried manually through the portal. If an endpoint fails consistently for 24 hours, it will be disabled to prevent excessive load on both our systems and yours. To re-enable it, simply activate the endpoint again in the portal.

​

Ordering

Webhooks are generally dispatched in the order they are created; however, this sequence is not guaranteed. It’s best not to rely on webhook order when integrating with Quartr webhooks.

​

Events are unfiltered

All webhooks are sent to every subscriber, regardless of their specific interests. It is the subscriber’s responsibility to filter the data they need. Moreover, because every change in the database is captured, you might receive multiple webhooks in rapid succession for the same entity. To manage potential peak loads, we recommend leveraging the provided rate limit values to ensure your system can handle the volume.

​

Response codes

We expect a 2xx response code for every webhook request. If the endpoint returns a different status code, the webhook is considered failed and will be retried according to the schedule above.

Here’s how we handle different response categories:

• 2xx (Success): Webhook successfully delivered. No retry.
• 3xx (Redirects): Treated as a failure, will retry using the retry schedule. Redirects are not followed, so please update your webhook URL if it changes.
• 4xx (Client errors): Treated as a failure, will retry using the retry schedule. These indicate an issue on your side (e.g. 404 Not Found, 401 Unauthorized):
• 5xx (Server errors): Treated as a failure. These are usually temporary issues. We will retry using the retry schedule.

Common failure scenarios include:

• Non-2xx status codes
• Timeouts (after 10 seconds)
• Connection issues or resets

After five failed attempts, the webhook is marked as failed and will appear as such in the portal. You can retry it manually or fix the issue and wait for the next webhook to be sent.