Set up webhook integration
Webhooks deliver real-time event notifications from Zenoti to your application. Instead of polling the API for changes, you register a destination URL and Zenoti sends an HTTP POST request with event data whenever a subscribed event occurs. This reduces API call frequency and provides near-instant data synchronization.
On this page
- Before you begin
- How webhooks work
- Manage webhook subscriptions
- Supported events
- Event response structure
- Failure handling and retries
- Tips
- Related articles
Before you begin
- You need a valid API key or access token. See Set up API authentication.
- Your destination URL must be publicly accessible and capable of receiving HTTP POST requests.
- Your endpoint must respond within 10 seconds.
- A bearer token is required for all webhook endpoint operations.
- Verify your organization hasn't reached the maximum webhook subscription limit (default: 40 subscriptions).
Permission: Manage API Keys, Manage Apps, and Manage Automation (under Administrator) -- Required to create backend applications and generate API keys.
How webhooks work
A webhook acts as an intermediary between Zenoti and your application. When an event occurs in Zenoti (for example, a guest is created or an invoice is closed), Zenoti sends an HTTP POST request to your registered destination URL with a JSON payload containing the event details.
Webhooks use standard HTTP methods (POST, PUT, PATCH) to deliver data. Your application processes the payload and responds with a 2XX status code to acknowledge receipt.
Manage webhook subscriptions
Zenoti supports two levels of webhook subscriptions:
- Organization-level β Events from all centers are sent to the webhook endpoint.
- Center-level β Events from specific centers only are sent to the webhook endpoint.
Access webhook management
- Navigate to Settings > Integrations > Webhooks.
- Select the appropriate tab:
- Organization β For organization-wide webhook subscriptions
- Center β For center-specific webhook subscriptions (if enabled for your organization)
The system displays existing webhook subscriptions with their name, subscribed event, status, and creation date.
Create a new webhook subscription
- Click Add Webhook or Create New Subscription.
- Configure the webhook details:
- Name β Enter a descriptive name for the webhook subscription
- Description β Add an optional description explaining the webhook's purpose
- Event Type β Select the Zenoti event that will trigger the webhook (such as appointment creation, guest registration, or invoice completion)
- Callback URL β Enter the external system's endpoint URL that will receive the event notifications
- Status β Set to Active to begin sending events immediately, or Inactive to create the subscription without triggering events
- If creating an organization-level webhook, optionally link specific centers:
- Select Filter by Centers if you want to limit events to specific centers
- Choose the centers from which events should be sent
- Leave unselected to receive events from all centers in the organization
- Click Save to create the webhook subscription.
The system validates that your organization hasn't exceeded the maximum allowed webhook subscriptions (default: 40) before creating the new subscription.
Edit or delete a webhook subscription
- From the webhooks list, locate the subscription you want to modify.
- Click the Edit icon next to the subscription.
- Update any of the following:
- Change the webhook name or description
- Modify the callback URL
- Switch the event type
- Update the active/inactive status
- Add or remove center filtering
- Click Save to apply your changes.
To delete a webhook subscription, click the Delete icon and confirm the removal.
Test webhook delivery
- After creating a webhook subscription, perform the action in Zenoti that triggers the subscribed event.
- Verify that your external system receives the webhook notification at the configured callback URL.
- If webhook delivery fails, check:
- The callback URL is accessible and responding to HTTP requests
- Your external system is properly handling the webhook payload format
- The webhook subscription status is set to Active
Supported events
| Entity | Events |
|---|---|
| Guest | Created, Updated, Deleted |
| Invoice | Closed, Payment Created, Payment Updated |
| Employee | Created, Updated, Deleted |
| Membership | Created, Freeze, Unfreeze, Cancelled, Reinstate, Renewed, Collection |
| Appointment | Started, Completed, Feedback |
| Class schedule | Created, Updated, Deleted |
| Class booking | Created, Updated, Deleted, Expired |
| Class status | Updated |
| Package | Created, Redeemed, Status Updated, Validity Updated, Price Updated |
| Product order | Created, Updated |
| Inventory transfer | Created |
| Purchase order | Created, Updated |
Event response structure
Every webhook delivery includes an HTTP header with a signature for authenticity verification and a JSON body with the event data.
HTTP body fields
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier for this webhook delivery |
| event_id | string | Unique identifier for the event |
| event_schema | string | The schema version (for example, v1) |
| event_resource | string | The entity type that triggered the event (for example, Guest, Invoice) |
| event_type | string | The specific event (for example, Guest.Created, Invoice.Closed) |
| event_timestamp | datetime | The UTC timestamp when the event occurred |
| data | object | Event-specific data payload |
Example payload
{
"id": "622b5b33a961750e01db6512",
"event_id": "622b5b33a961750e01db6510",
"event_schema": "v1",
"event_resource": "Invoice",
"event_type": "Invoice.Closed",
"event_timestamp": "2022-03-11T14:22:43.384Z",
"data": {}
}
Failure handling and retries
Zenoti uses the following failure handling process for webhook deliveries:
| Parameter | Value |
|---|---|
| Response timeout | 10 seconds |
| Maximum retries | 5 reconnection attempts |
| Retry delay | Exponential backoff, 30 seconds minimum to 10 minutes maximum |
| Auto-deactivation | After 20 consecutive failures |
What happens when a webhook fails
- If your endpoint does not respond within 10 seconds, Zenoti marks the delivery as failed.
- Zenoti retries the delivery up to 5 times with exponential backoff delays.
- If failures continue and reach 20 consecutive failures, Zenoti automatically deactivates the webhook, generates an error log, and sends a failure notification email.
Recover a deactivated webhook
- Verify that your destination URL is operational and accessible.
- Review the webhook failure logs to identify the cause of the failures.
- Correct any errors at your destination URL.
- Re-enable the webhook from the inactive webhooks tab in Zenoti.
Tips
- Design your webhook endpoint to respond quickly (under 10 seconds). Process the payload asynchronously if your business logic takes longer.
- Implement idempotent processing using the
idfield to handle potential duplicate deliveries. - Use the
event_schemafield to handle schema version changes gracefully. - Monitor your webhook failure logs regularly to catch issues before auto-deactivation occurs.
- Verify webhook authenticity using the HTTP header signature before processing the payload.