> For the complete documentation index, see [llms.txt](https://docs.zotlo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zotlo.com/integrating-zotlo/webhooks/webhooks-overview.md).

# Webhooks Overview

Zotlo Webhooks allow your backend to receive real-time notifications about events such as subscription status changes, successful payments, registered users, completed quizzes and refunds. 

Your server receives these events as **HTTP POST requests** in JSON format, enabling you to sync billing activity, update user access, trigger workflows, or maintain your internal records.

## **Activation**

To start receiving webhook events, you must activate each webhook type from the Zotlo Dashboard:

1. Navigate to **Developer Tools → Webhooks**.
2. Enter your server’s **endpoint URL** for the webhook(s) you want to subscribe to.
3. Once saved, the webhook becomes **active immediately**.
4. You can use the **“Send Test Webhook”** option to verify connectivity and validate your endpoint before going live.

## **How Webhooks Work**

Webhooks are delivered to the endpoint URL once they are activated.

Each webhook event is sent as a **POST request** with a JSON body containing:

* **queue** : event metadata
* **parameters** : actual event payload (subscription, payment, or refund details)

Example structure:

{% code overflow="wrap" %}

```json
{
  "queue": {
    "type": "...",
    "eventType": "...",
    "requestID": "...",
    "createDate": {...},
    "appId": 123
  },
  "parameters": { ... }
}
```

{% endcode %}

## **Delivery & Retry Logic**

A webhook is considered successful when your server returns **HTTP 200**.

If your server returns anything other than 200, the notification is retried with the following schedule:

| Attempt       | Delay            |
| ------------- | ---------------- |
| 1st retry     | 10 minutes       |
| 2nd–4th retry | Every 30 minutes |
| 5th retry     | After 1 hour     |
| Final state   | No more retries  |

If all attempts fail, the event is dropped and will not be resent.

## **Security Best Practices**

To ensure webhook authenticity, you should:

* Validate the IP/domain whitelist (optional).
* Verify the **requestID** does not repeat (idempotency check).
* Log all incoming events.
* Always return **200 OK** after successful processing, not before.

## **Event Types**

Zotlo currently provides three webhook categories:

| Webhook                         | Description                                                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Subscription Status Webhook** | Sends events on subscription lifecycle changes (new subscriber, grace, renewal, cancellation, reactivation, etc.) |
| **Payment Webhook**             | Sends events for all successful payments (subscription & consumables)                                             |
| **Refund Webhook**              | Sends events for all successful refund operations                                                                 |
| **Registered Users Webhook**    | Sends events for all successful user registrations                                                                |
| **Completed Quizzes Webhook**   | Sends events for all completed quizzes                                                                            |

Each webhook type includes its own `queue.type`, `eventType`, and structured `parameters` payload.

Detailed specs for each webhook type are provided on their respective documentation pages.

## **Recommendations**

To ensure consistent processing:

* Treat all webhooks as **asynchronous**.
* Use **transaction\_id** and **subscriber\_id** as primary identifiers.
* Use **realStatus** instead of **status** when determining true subscription state.
* Apply **idempotent handling** to avoid duplicates.
* Process events in chronological order using `createDate` when needed.

## **Sample Response Structure**

While the payload differs per webhook type, all webhook POST bodies follow the same structure:

| Field               | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| **queue.type**      | Type of webhook (SubscriberUpdate, TransactionInsert, TransactionRefund) |
| **queue.eventType** | Specific event (renewal, newSubscriber, refund, transaction, etc.)       |
| **parameters**      | The event data (subscription profile, payment details, refund details)   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zotlo.com/integrating-zotlo/webhooks/webhooks-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.