Creating a Webhook Endpoint

Availability: all plans

A webhook is a way for ServiceVisit to tell another system when something happens in your account. You register an endpoint, which is the address of the receiving system, and ServiceVisit sends it a message each time a chosen event occurs, such as a job being created or an invoice being paid. Each message is sent as JSON and signed so the receiving system can check it really came from ServiceVisit. Webhooks suit a developer or an integration partner who is building something that reacts to your account activity. If you only need to connect your accounting system, see the accounting integration overview instead.

Before you start

You need the role access that allows managing integrations. If your role lacks it, the Webhooks card on the Integrations page shows "Role required" and a "Why can't I use this?" link instead of a Manage button. Ask whoever administers users on your account to change your role.
Have the endpoint address ready from the person or vendor building the receiving system. It must be a public, secure (https) address. An address that is not secure, or that is not a full address, is rejected.
You can have up to 10 webhook endpoints. Deleted endpoints do not count toward that limit.

Steps

Go to Settings, open Integrations, and on the Webhooks card choose Manage. The page is titled Webhook Endpoints.
Choose New Webhook. If you have no endpoints yet, the same button appears under "No webhook endpoints yet".
In Name, type a label that helps you recognize this endpoint, for example "Production integration". It can be up to 200 characters.
In Endpoint URL, enter the endpoint address you were given. It can be up to 1000 characters.
Under Events, leave All events ticked to receive every event ServiceVisit offers, now and in the future. To receive only some, untick All events and tick the individual events you want. The next guide explains the event list.
Choose Create Webhook. To back out, choose Cancel.
The page now shows "Webhook endpoint created" and a signing secret. Choose Copy and store the secret safely right away, then give it to whoever builds the receiving system. It is shown only this once. Choose Done to return to the list.
Back on the list, choose the send icon (its tooltip says "Send test event") on your new row. A message says the test event is queued. Check the delivery log to confirm it arrived.

Tips

Use Send test event after every change to the endpoint address or secret. The test goes through the same signing and delivery path as real events, so a successful test is good evidence the real ones will work.
To change an endpoint later, use the pencil icon (tooltip "Edit"). You can rename it, change the address, change the events, switch it Active on or off, and open Advanced delivery settings for the timeout in seconds, the maximum number of retries and the number of failures after which it is switched off automatically. New endpoints start with a 30 second timeout, 3 retries and automatic switch-off after 10 failures in a row.
The list shows each endpoint's name, address, events ("All events" when none are singled out), status and last delivery. Status is Active, Disabled, or a count such as "3 failing".
The trash icon (tooltip "Delete") asks you to confirm and then stops the endpoint receiving events immediately.

If something goes wrong

If you see "Failed to create webhook endpoint. Check the endpoint URL and try again.", check that the address is complete and secure. Also check you have not reached the limit of 10 endpoints.
If you see "Name and endpoint URL are required.", fill in both fields.
If you lose the signing secret, open the endpoint with the pencil icon and use Rotate Signing Secret. See the signing secret guide.
If the test event never arrives, open the delivery log for the endpoint. It records the response the receiving system gave.

Webhook Events and the Signing Secret — Every webhook endpoint listens for a set of events, and every message it receives is signed with a secret that only you and the receiving system know. This guide covers choosing which events an…
Webhook Delivery Log, Retries and Disabling — When ServiceVisit sends an event to a webhook endpoint, it records what happened. This guide explains how to read that record, how failed deliveries are retried, and how an endpoint ends up switched…
Manage integrations — ServiceVisit has an Integrations page under Settings where you connect ServiceVisit to other systems. It has two parts.
Accounting integration with QuickBooks Online and Xero — The accounting integration sends your ServiceVisit invoices, payments, refunds, customer credits and approved technician time to your accounting system, so your bookkeeper does not retype them. It…