ZenotiHelp

Set up webhook integration

ZTZenoti Docs Team Updated March 7, 2026 4 min readGuide

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

  • 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

  1. Navigate to Settings > Integrations > Webhooks.
  2. 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

  1. Click Add Webhook or Create New Subscription.
  2. 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
  1. 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
  1. 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

  1. From the webhooks list, locate the subscription you want to modify.
  2. Click the Edit icon next to the subscription.
  3. 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
  1. Click Save to apply your changes.

To delete a webhook subscription, click the Delete icon and confirm the removal.

Test webhook delivery

  1. After creating a webhook subscription, perform the action in Zenoti that triggers the subscribed event.
  2. Verify that your external system receives the webhook notification at the configured callback URL.
  3. 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

  1. If your endpoint does not respond within 10 seconds, Zenoti marks the delivery as failed.
  2. Zenoti retries the delivery up to 5 times with exponential backoff delays.
  3. 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

  1. Verify that your destination URL is operational and accessible.
  2. Review the webhook failure logs to identify the cause of the failures.
  3. Correct any errors at your destination URL.
  4. 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 id field to handle potential duplicate deliveries.
  • Use the event_schema field 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.
Was this article helpful?
Your feedback helps us improve our documentation.