Overview
Webhooks are an advanced feature used to connect Zenbooker to external apps. They are mainly for developers, so don't worry if you're not using them.
Webhooks are notifications sent over the web containing data about your jobs, recurring bookings, service requests, and more. These notifications are sent to your HTTP endpoints. You define a URL and the type of event for which Zenbooker should send notifications. When an event for which you've created a webhook happens, Zenbooker will make a POST request with relevant data attached to a JSON payload.
To get started with webhooks, go to Settings > Developers > Webhooks from your Zenbooker admin.
Events
When configuring a webhook, you select the type of event for which you would like to receive payloads. You can only specify one event type per webhook, but you can create multiple webhooks for the same endpoint URL for each event type you need.
Job created job.created
Triggered whenever a new job is created. Including jobs created from the Zenbooker admin, booked by customers, and jobs created as part of a recurring booking.
Job rescheduled job.rescheduled
Triggered whenever a customer or a staff member reschedules a job. Also triggered when a recurring booking's frequency is edited, and upcoming jobs in the recurring series are automatically rescheduled.
Job canceled job.canceled
Triggered whenever a customer or a staff member cancels a job. Also triggered when an upcoming job is canceled due to a recurring booking being canceled.
Job assigned job.service_providers.assigned
Triggered whenever service providers are assigned or unassigned to an existing job. The trigger does not activate when service providers are assigned while creating a new job in the Zenbooker admin.
Job marked en-route job.enrouteTriggered whenever a job is marked as en route.
Job started job.startedTriggered whenever a job is marked as In Progress or when the Start Job button is clicked.
Job completed job.completedTriggered whenever a job is marked as Complete
Recurring booking created recurring_booking.created
Triggered whenever a new recurring booking is created.
Recurring booking canceled recurring_booking.canceled
Triggered whenever a recurring booking is canceled.
Payload structure
Each webhook payload includes a top-level object with the following standard fields:
eventThe event type that triggered this notification.accountThe Zenbooker account ID of the business where the event occurred.webhook_idThe ID of the webhook configuration to which this notification belongs.retry_countThe number of times Zenbooker has tried to resend this webhook if the first attempt failed.
The data field contains event-specific information, such as job or invoice details.
Inspecting payloads
Payloads vary depending on the event. To see what the data looks like for each type:
Use requestcatcher.com or a similar service to create a temporary webhook URL.
Paste that URL into the Webhook URL field for one of your webhook configurations in Zenbooker.
Click the Test button next to the webhook to send a sample payload.
This lets you quickly inspect real webhook data in a test environment without writing any code.
Responding to a webhook payload
Your webhook endpoint must return a 2xx status code to acknowledge the receipt of a webhook event. Any other status code as a response will be treated as a delivery failure and Zenbooker will attempt to resend the webhook.
Webhook retries
If a webhook delivery attempt fails, Zenbooker will make up to four more attempts to send the payload (at increasing intervals). If all of these attempts fail, Zenbooker will disable the webhook and email you to inform you.