ServiceM8

The ServiceM8 Developer Portal

Welcome to the ServiceM8 developer portal. You'll find comprehensive guides and documentation to help you start working with ServiceM8 as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

🚧

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.

Parameter

Value

mode

subscribe

challenge

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

Code

Title

Description

200

Success

Webhook has completed successfully

410

Gone

Webhook will be unsubscribed (the same as if you had called the webhook subscription endpoint and removed it)

429

Throttled

Webhook request volume will be gradually throttled for 15 minutes for this account

4xx/5xx

Error

Webhook will be retried for up to 72 hours, before automatically being cancelled

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

Updated about a year ago

Overview


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.