# 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)   |