Functions for ServiceM8 Add-ons take input in the form of data about an event that has happened, and produce output which is HTML and Javascript to be rendered in the ServiceM8 UI.

Events may be generated by the user clicking an Action button that your add-on has created in the web interface or in the mobile app (refer to the actions parameter of the Manifest Reference), or from changes to field values in ServiceM8 records such as Jobs or Clients (refer to the webhooks parameter of the Manifest Reference).

Input Provided

When an event happens, ServiceM8 invokes your Simple Function or callback URL with details about the event. For Simple Functions, this is provided as the event argument to your handler function. For web service callback URLs, the event object will be provided as a JSON Web Token (JWT) sent in the HTTP request body.

The event object has the following properties:

Preferences for hosted Simple Functions

When an active ServiceM8-hosted Simple Function Add-on declares manifest preferences, ServiceM8 includes a top-level preferences object in its SDK events. Externally hosted web services and developer-hosted Lambda functions do not receive this object.

For example, this fragment shows the preferences supplied after a user saves settings in Settings → Preferences → Add-ons:

{
  "preferences": {
    "quote_title": "Cat enclosure quote",
    "quote_notes": "Please confirm access before installation.",
    "include_installation": false,
    "default_enclosure": "balcony"
  }
}

Read values from event.preferences, not event.eventArgs. ServiceM8 supplies only currently declared keys, using the account's saved values or the manifest defaults for keys without saved values. Text and select values are strings; boolean preferences remain JSON booleans. No additional OAuth scope or API call is needed, and client-supplied event arguments cannot override this object.

Read preferences inside your handler. The fallback below also handles Add-ons that do not declare preferences:

const preferences = event.preferences ?? {};
const quoteTitle = preferences.quote_title ?? "Your quote";
const includeInstallation = preferences.include_installation ?? true;

Use ?? for any local fallback so that saved false and empty strings remain valid values. Changing this event object does not persist settings; users save them through Preferences. Escape preference strings for the output context if you include them in HTML.

eventArgs for action events

Action events occur when the user clicks a button in the Job Card or Client Card that was created by the actions section of your add-on's manifest.

eventArgs for webhook events

Webhook events occur when a field value changes on a record for which a webhook is registered in the webhooks property of your add-on's manifest.

Example event argument for an Action

This is an example of the event argument which would be provided to your Simple Function or callback URL when a user clicks your add-on's button from the Job Card.

{
    "eventVersion":"1.0",
    "eventName":"hello_addon_event",
    "auth": {
        "accountUUID": "5e32b1f1-bb9f-457a-a67c-44dd7ff8ac1b",
        "staffUUID":"9d914a06-221e-4013-8b4d-2735272710eb",
        "accessToken":"9cd88543362a447291cfc362e3ce86f73d94eb2d",
        "accessTokenExpiry":900
    },
    "eventArgs": {
        "jobUUID":"0686ce69-4a5d-4f73-ad56-827ffaaced2b"
    }
}

Example event argument for a Webhook

This is an example of the event argument which would be provided to your Simple Function or callback URL when a job record's status field changes, and your add-on's manifest has registered a webhook to be notified of changes to that field.

{
    "eventVersion":"1.0",
    "eventName":"webhook_subscription",
    "auth": {
        "accountUUID": "5e32b1f1-bb9f-457a-a67c-44dd7ff8ac1b",
        "staffUUID":"9d914a06-221e-4013-8b4d-2735272710eb",
        "accessToken":"9cd88543362a447291cfc362e3ce86f73d94eb2d",
        "accessTokenExpiry":900
    },
    "eventArgs": {
        "object":"job",
        "entry": [{
            "uuid":"0686ce69-4a5d-4f73-ad56-827ffaaced2b",
            "changed_fields":["status"],
            "time":"2017-01-01 12:21:12"
        }],
        "resource_url":"https://api.servicem8.com/api_1.0/Job/0686ce69-4a5d-4f73-ad56-827ffaaced2b.json"
    }
}

Output Required

For Webhook events, no output from your function is required. Any return value provided in response to Webhook events will be ignored. The only requirement is that your function completes its processing and returns before the timeout expires.

For Action events, i.e. events generated when a user clicks one of your add-on's buttons in the ServiceM8 UI, your function must return HTML and javascript to be rendered inside a window in the ServiceM8 UI. This will be rendered inside an iframe, so it must be a complete HTML document including <html>, <head> and <body> tags. Refer to the Examples to see how to render appropriate HTML.

You can use javascript contained in your returned HTML to implement client-side functionality such as resizing or closing your add-on's popup window. Refer to the Client API documentation for more information.