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:

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

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)