Configure webhooks and automation
Webhooks allow external systems to receive real-time HTTPS notifications when specific events occur in Zenoti. This article covers the Zenoti-side administrative workflow: creating and managing webhook subscriptions, testing delivery, and handling delivery failures. Event schemas and payload contracts are not documented here β they live in the Zenoti APIs category.
On this page
- Before you begin
- External-system prerequisites
- Network requirements
- Webhook subscription limits
- Create a webhook subscription
- Test a webhook subscription
- Edit, deactivate, or delete a subscription
- Monitor delivery and read logs
- Organization and center scope
- Failure paths: delivery failures
- Tips
- Troubleshooting
- Related articles
Before you begin
Permission: Manage Automation under Api in the Administrator section of the security role β required to create, edit, delete, and manage webhook subscriptions. Administrators with access to Configuration > Integrations > Webhooks typically hold this permission.
- The Webhooks row is available. Webhooks appears under Configuration > Integrations only when automation access is on for your organization and your role holds the permission above.
- HTTPS endpoint ready on your side β see the next section.
- Event catalogue reviewed. The available event types are documented in the Zenoti APIs category. Do not rely on anecdotal lists. The following event-specific reference pages are available:
External-system prerequisites
These are on your side, not Zenoti's:
- Public HTTPS endpoint. Webhook receivers must be reachable over HTTPS from the public internet. Zenoti does not deliver to HTTP endpoints. Self-signed certificates are not accepted β use a certificate from a public trust store.
- Signature verification. Your receiver should verify the webhook signature to confirm the payload originated from Zenoti. Signing details are documented in the Zenoti APIs category.
- Idempotency. Zenoti retries failed deliveries (see Failure paths). Your receiver must be safe to re-invoke for the same event β deduplicate by the delivery or event ID.
- Logging. Log every delivery (success and failure). Webhook debugging without receiver-side logs is extremely difficult.
- A named owner. Assign a business owner to each subscription. When the owner leaves, the subscription must be audited and deactivated if unused.
Note: Webhook event names, payload schemas, and handler implementation belong in the Zenoti APIs category. This article stops at the subscription-management boundary.
If you are setting up webhook integration for the first time or need to inspect existing subscriptions programmatically, the following Zenoti APIs references are the starting point:
Network requirements
Webhook delivery is outbound from Zenoti to your endpoint. Your infrastructure must accept inbound traffic from Zenoti.
| Direction | Endpoint | Port | Notes |
|---|---|---|---|
| Zenoti β Your endpoint | Your webhook receiver URL | 443 (HTTPS) | Must use HTTPS with a publicly trusted TLS certificate. |
| Your endpoint β (optional outbound) | None required by Zenoti | β | Your receiver does not need to call back to Zenoti to acknowledge a delivery. HTTP 200 is the acknowledgement. |
If your receiver sits behind a firewall, allow inbound HTTPS from the Zenoti tenant's egress IP range. Contact Zenoti Support for the current published range if your organization enforces strict allowlists.
Webhook subscription limits
Each organization has a maximum number of webhook subscriptions (default 40). This limit is configured per organization.
- When you reach the cap, creating a new subscription is blocked until you delete or deactivate an existing one.
- To request an increase, contact Zenoti Support β mention the business case and the number you need.
- Count subscriptions carefully when multiple teams use the same tenant. One subscription = one event-to-endpoint binding, regardless of volume.
Create a webhook subscription
Navigate to Configuration > Integrations > Webhooks.
Select Create a webhook. Create webhooks listener opens on step 1 | Select the event (the counter reads
0 event selected).Pick the event. The rail on the left filters the event cards by category β All, Appointment, AppointmentGroup, Blockout, Class, Employee, GroupInvoice, Guest, Invoice, Prescription, Product, Room, and others β and each card names the event and when it is triggered. Tick the event you need (the counter changes to
1 event selected), then select Next. Refer to the event reference pages in the Zenoti APIs category for what each event carries.On step 2 | Fill the form, configure the listener:
Field What to enter Name Descriptive label β include the consumer and purpose. Description Owner, business purpose, and runbook link. Subscription Type Organization (the default) or Center. Choosing Center lets you pick the centers whose events the listener receives. Request Type The HTTP verb Zenoti uses for the delivery ( Select HTTP verb).URL The HTTPS URL where Zenoti will send event payloads ( Enter URL).Secret The shared secret your receiver uses to verify the delivery signature. Headers Optional custom headers as Key / Value pairs; select Add for each. The SELECTED EVENTS panel on the right shows the event you picked, tagged with its category; Edit returns to step 1.
Select Complete. The listener is created and appears in the webhook list, where you can deactivate it until your receiver has been tested.
Worked example
A development team wants to receive real-time notifications when a gift card is issued at the downtown center. They create a subscription named "Gift card issued β Downtown," select the gift card issued event, enter https://integrations.example.com/zenoti/gift-cards as the callback URL, link only the Downtown center, and save with status Inactive. After a successful test event, they set the status to Active.
Test a webhook subscription
- In the webhook list, open the subscription.
- Select Verify.
- Zenoti sends a sample payload to your endpoint.
- Verify on your receiver side:
- The HTTPS request arrived.
- Your signature verification accepted it.
- Your handler returned HTTP 200 within the timeout.
- If any of the above fails, do not activate the subscription in production yet β debug until the test event succeeds end-to-end.
Edit, deactivate, or delete a subscription
Both active and inactive subscriptions can be edited or removed. There is no "voided" state β the state machine is Active β Inactive, plus hard delete.
- Edit active subscription. Changes take effect for subsequent events. In-flight events continue on the old configuration; there is no way to replay events that already fired.
- Edit inactive subscription. Changes apply when the subscription is reactivated.
- Deactivate. Suspends delivery. No events are queued while inactive β events that occur during the inactive window are not replayed on reactivation.
- Delete. Permanent. Deletion also frees the slot in the subscription-cap count.
If an endpoint URL changes, edit in place rather than delete and recreate; the existing subscription history stays intact.
Monitor delivery and read logs
Webhook execution logs are visible to administrators when the organization's webhook log visibility setting is on. The logs show each attempted delivery, HTTP response code, latency, and any retry attempts.
If log visibility is off, logs are suppressed in the UI. In that case, your receiver-side logs are the only visibility into delivery. Keep receiver logs detailed enough to diagnose failures independently.
Organization and center scope
Webhook management is an organization-scope surface: the Webhooks row renders under Configuration > Integrations at organization scope once automation access is on for the organization. A listener's own reach is set by its Subscription Type β Organization delivers events from every center, Center restricts delivery to the centers you select on the form.
The Manage Automation permission under Api is required regardless of scope.
Failure paths: delivery failures
Webhooks are fire-and-forget from the application's perspective, but delivery can fail for many reasons. The table lists each failure mode, what an administrator sees, and the resolution.
| Failure mode | User-visible symptom | Resolution |
|---|---|---|
| Endpoint unreachable (DNS, 5xx, timeout) | Delivery logs show repeated failures; no data arrives at your system. | Zenoti retries automatically with backoff. Investigate your receiver availability and fix. Once the endpoint recovers, future events flow; events during the outage are not replayed automatically β coordinate backfill through the Zenoti API if needed. |
| HTTPS / TLS failure | Delivery fails before the payload is transmitted. | Ensure a valid publicly trusted certificate on the endpoint. Confirm TLS version compatibility. |
| Endpoint returns non-2xx | Delivery logs show the response code; event is retried up to the retry cap. | Diagnose the receiver. If the receiver rejects the payload shape, your handler needs to handle it or return 2xx and drop silently. |
| Endpoint returns 2xx but your system rejected the event internally | Zenoti considers the delivery successful even though nothing was done. | Fix the receiver β only return 2xx after the event has been durably accepted on your side. |
| Signature verification failing | Your receiver sees events as "untrusted" and rejects them. | Confirm signature configuration. See the Set up webhook integration reference in the Zenoti APIs category. |
| Subscription inactive | No events are delivered; logs show no attempts. | Activate the subscription. Events during the inactive window are lost. |
| Subscription cap exceeded | Cannot create a new subscription. | Delete unused subscriptions or request a cap increase from Zenoti Support. |
| Endpoint SSL certificate expired | Delivery fails with TLS error. | Renew the certificate on your side. Zenoti does not accept self-signed or expired certs. |
| Auth header change on receiver | Your receiver starts returning 401 to legitimate events. | Update the receiver to accept Zenoti's signing scheme; refer to the Use webhook event APIs reference for header validation details. |
| Receiver latency causes timeout | Delivery marked failed because the response took too long. | Move heavy processing to an async queue on your receiver; acknowledge with 2xx quickly and process the payload in the background. |
Retry behaviour uses exponential backoff. After the retry budget is exhausted, the event is considered permanently failed. There is no automatic replay β use the Zenoti API to backfill data gaps.
Tips
- Activate subscriptions only after a successful test event end-to-end.
- Use one subscription per event-to-endpoint binding. Do not multiplex multiple event types into one URL unless your handler can cleanly dispatch.
- Secure your endpoint using signature verification β see Set up webhook integration.
- Monitor receiver-side logs for latency trends β slow receivers hit retry thresholds as volume grows.
- Deactivate or delete subscriptions you no longer need to stay within the cap.
- Link subscriptions to specific centers when you only need events from a subset of your organization's centers β this reduces noise at your receiver and makes filtering simpler.
Troubleshooting
The Webhooks page is not visible under Configuration > Integrations. Automation access is not on for your organization, or your security role lacks the Manage Automation permission under Api in the Administrator section. Confirm the permission on the role first.
I can see the Webhooks page but cannot restrict a listener to specific centers. Set Subscription Type to Center on step 2 | Fill the form; the center list appears only for that type.
A new subscription cannot be saved β the system shows an error when I select Save. Your organization has reached the maximum subscription limit (default 40). Delete or deactivate unused subscriptions to free a slot, or contact Zenoti Support to request a higher limit.