Web Service Hosted Add-ons

If you already have your own cloud infrastructure you can write a web service and host it with any cloud hosting provider. In your Add-on's settings, you specify the URL of a callback URL which will be invoked whenever the user performs one of the Actions configured in your App's Manifest. The callback URL must accept POST requests over HTTPS. ServiceM8 sends requests to your web service and your service takes any necessary actions and then sends back a response. You can write your web service in any language.

Input Provided

Your callback URL will be invoked by a HTTP POST, where the request body is a JSON Web Token (JWT). The data encoded into the JWT is identical to the event argument provided to Serverless Add-ons.

The JWT is signed using the HMAC-SHA-256 algorithm with your Add-on's App Secret as the key. Only you and ServiceM8 know your Add-on's App Secret; this ensures that only ServiceM8 can produce valid JWTs to invoke your callback URL.

Output Required

Output provided by your callback URL will be rendered into the ServiceM8 UI inside an iframe. Ensure that you do not set the X-Frame-Options header to a value that prevents your content from being rendered in an iframe.

CSS styles inside your rendered content should be based on the base templates provided by ServiceM8's CSS reset file.

Include the Client JS SDK to implement interactions such as window resizing, closing, or invoking your callback URL again.

Key points to remember

• HTTPS is mandatory
  Your add-on endpoint must accept requests over HTTPS.
• Callback URL
  When setting up your add-on within ServiceM8, your callback url is the endpoint of your web service. This endpoint URL must handle/route all events you wish your add-on to respond to.
• Add-on Activation URL
  The add-on activation URL is where a user is initially redirected when they have chosen to activate/install your add-on from the ServiceM8 Add-on store.
• Iframe Support
  Your web-service will be rendered within an iframe on the ServiceM8 platform, so make sure you have not denied iframe support via the X-Frame-Options header.
• OAuth Authentication is mandatory
  To use an external integration, or a web service hosted add-on, you will need to implement the OAuth2 flow between your app and ServiceM8. You should set the activation url to the start of your OAuth flow so users are able to provide authentication to their account immediately after activating your add-on. Keep in mind, you might not have seen this user before - so ensure they are either already authenticated with your app, or prompt them to login/signup to a new account.

Once your app has completed the OAuth authentication flow, your add-on will be activated within the ServiceM8 account.