🚧

Public Applications Only

The ServiceM8 Webhooks API is only available to Public Applications. You will need to implement OAuth 2.0 Authentication and obtain an access token before you can use the Webhooks API.

What is a Webhook?

A Webhook is a tool for retrieving and storing data from a certain event. They allow you to register an http:// or https:// URL where the event data can be received in JSON formats.

ServiceM8 Webhooks are commonly used for:

• Receiving scheduling changes
• Updating item/material’s price changes in your app
• Notifying staff with real-time job changes
• Collecting data for data-warehousing
• Integrating your accounting software

Think of it this way, if you would otherwise have to poll for a substantial amount of data, you should be using webhooks.

📘

Note that updates only indicate that a particular field has changed, they do not include the value of the field. When your application receives a webhook update from ServiceM8, you will need to use the REST API to retrieve the record and get the field values.

Creating and Updating Subscriptions

Webhooks are subscribed to by using the Webhooks API endpoint: https://api.servicem8.com/webhook_subscriptions

The basic operations are:

• Add or modify a subscription.
• List each of your existing subscriptions.
• Delete subscriptions.

Setting Up your Callback URL

First you’ll need to prepare the page that will act as your callback URL. This URL will need to be accessible by ServiceM8 servers, and be able to receive form-encoded POST data that is sent when an update happens, and in order to verify subscriptions.

This URL should always return a HTTP 200 response when invoked by ServiceM8.

Handling Verification Requests

When you add a new subscription, or modify an existing one, ServiceM8 servers will make a HTTP POST request to your callback URL in order to verify the validity of the callback server. The request will include the following POST parameters.

When your server receives one of these requests, it needs to render a response to the request that includes only the challenge value. This confirms that this server is configured to accept callbacks, and is used for security verification on ServiceM8’s side.

Here's a simple example of how to implement the verification step.

<?php

if ($_REQUEST['mode'] == 'subscribe' && $_REQUEST['challenge']) {
    echo $_REQUEST['challenge'];
} // else: handle webhook POST data

Handling Webhooks

After your callback URL has been verified, ServiceM8 will send a HTTP POST to that URL each time one of the fields on the subscribed object changes. The data POSTed to your callback URL will be JSON in the following format:

{
 "object": "job",
 "entry": [{
   "changed_fields": ["badges","generated_job_id"],
   "time": "2015-01-01 00:00:00",
   "uuid": "de305d54-75b4-431b-adb2-eb6b9e546013"
 }],
 "resource_url": "https://api.servicem8.com/api_1.0/job/de305d54-75b4-431b-adb2-eb6b9e546013.json"
}

The entry parameter is an array which contains a single object. To read the values you'll need to use code similar to myValue = entry[0].time.

Note that the data POSTed to your callback URL does not contain the object itself — only the UUID and a list of fields that changed. You can request the URL specified by resource_url to obtain the object itself. The timestamp provided will be in UTC.

📘

Most timestamps in ServiceM8 are in the account's local timezone. Webhooks are different, as they use UTC timestamps.

Callback URL Response Codes

How to Use the Webhooks API

Refer to the Webhooks API Reference for details of the Webhooks endpoint.

Which objects support webhooks?

The following objects/endpoints support webhooks:

• Job Activity
• Job
• Job Payment
• Note
• Task
• Material
• Company
• Attachment
• Form Response