Webhook Events and the Signing Secret

Availability: all plans

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 endpoint receives, reading the sample messages ServiceVisit shows you, and managing the signing secret, including replacing it.

Before you start

• You need the role access that allows managing integrations.
• The endpoint must already exist, or you can choose events while creating it. See the guide on creating a webhook endpoint.

Steps

Choose the events

1. Open Settings, then Integrations, then Manage on the Webhooks card.
2. Choose New Webhook, or the pencil icon (tooltip "Edit") on an existing endpoint.
3. Look at the Events section. All events is ticked by default on a new endpoint. While it is ticked the individual boxes are greyed out. All events means every event listed now and any event added later.
4. To pick specific events, untick All events. The events are grouped under headings: Jobs, Work Orders, Assessments, Estimates, Billing, Property History and Customers.
5. Tick each event you want. Each one shows its name and a one-line description. The events offered are:
   • Jobs: Job created, Job status changed.
   • Work Orders: Work order assigned, Work order completed, Change order created, Change order approved.
   • Assessments: Assessment created, Assessment completed.
   • Estimates: Estimate sent, Estimate accepted, Estimate declined.
   • Billing: Invoice created, Invoice sent, Invoice paid.
   • Property History: Service event recorded.
   • Customers: Customer created, Marketplace request received.
6. Under any event, open Sample payload to see an example message in the exact shape the receiving system will get. Hand this to whoever builds the receiver.
7. Choose Create Webhook or Save Changes.

Verify messages with the signing secret

1. Copy the signing secret when it is shown after you create the endpoint. It cannot be shown again.
2. Give the secret to the receiving system. Every message carries a signature in a header named X-ServiceVisit-Signature, made with HMAC-SHA256. The receiver recomputes the signature with the secret and rejects anything that does not match.
3. On the edit page, the heading area shows the last four characters of the current secret, written as "Signing secret ends in" followed by those characters. Use it to tell which secret an endpoint is currently using.

Replace the secret

1. Open the endpoint with the pencil icon.
2. Choose Rotate Signing Secret at the bottom of the page.
3. Confirm. The page says "Signing secret rotated" and shows the new secret once. Choose Copy and give it to the receiving system.

Tips

• Subscribe only to the events you need. A narrower list means less traffic for the receiving system to handle.
• Some events, such as Job created, Service event recorded, Customer created and Marketplace request received, contain customer names, contact details or Property addresses. Make sure the receiving system is one you trust with that information.
• You cannot save an endpoint with All events unticked and nothing selected. Choose at least one event, or tick All events.
• Rotate the secret if you think it has been shared by mistake or when someone who knew it leaves.

If something goes wrong

• After rotating, the old secret stops working immediately. Until the receiving system is updated, its signature checks fail. The confirmation message warns about this. Update the receiver, then use Send test event from the list to confirm.
• If the page says "Failed to rotate the signing secret.", try again. If it repeats, contact support.
• If you did not copy a new secret in time, rotate again to get another.

Related articles

• Creating a Webhook Endpoint — 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…
• 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…