Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Mitti (SafetyCulture) Alerts

Overview

Mitti (formerly SafetyCulture) is a frontline operations platform used for inspections, issue reporting, and corrective actions. When a food safety problem is reported as an Issue in Mitti, you want the right people to hear about it immediately, wherever they are standing.

Mitti's webhooks send an HTTP POST to a URL you choose whenever an event happens in your organization, including when an Issue is created. This page connects that event to the Relay Alerts API: a food safety Issue is created in Mitti, a small receiver you host checks it, and every device in the target Workflow Group speaks the message until someone taps the talk button to accept the job.

This page builds a complete, working food safety alert.

Why Alerts and not Broadcasts

Relay offers two notification types. Use Alerts for food safety. An alert repeats every 30 seconds until a human acknowledges it, and it records who accepted the job, which is the accountability a food safety response needs. A broadcast plays once with no acknowledgement. That is fine for shift announcements, but wrong for a cooler failure.

Why a receiver sits in the middle

Unlike many integrations, Mitti cannot call Relay directly. A Mitti webhook registration takes only a list of events and a destination URL. It cannot add a custom Authorization header or reshape the body, and Relay requires both. Mitti's payloads are also deliberately small, so details such as the issue title, category, and site must be fetched from the Mitti API.

The receiver in this guide is a small piece of JavaScript with a thin adapter for Azure Functions, AWS Lambda, or Cloudflare Workers. It does four jobs:

  1. Verifies that the request really came from Mitti, using the HMAC signature Mitti attaches to every webhook.

  2. Fetches the issue from the Mitti API and checks that it is a food safety issue.

  3. De-duplicates, because Mitti retries failed deliveries and may deliver the same event more than once.

  4. Calls Relay with a message written for text-to-speech.


Prerequisites

Side
Requirement

Relay

An enterprise plan account. API keys are not available on lower tiers.

Relay

A Workflow Group containing the users who should receive food safety calls.

Relay

Your subscriber ID and an API key.

Mitti

A Premium or Enterprise plan. API tokens are not available on lower plans.

Mitti

An Issue category used for food safety (this guide uses Food safety). Categories are configured in your Mitti organization.

Mitti

An API token whose owner can receive webhooks. For a service user token, that means the Override permissions: Manage all data permission. For a user token, the user needs the Administrator permission. See Step 4.

Hosting

A place to run the receiver at a public HTTPS URL: an Azure Function App, an AWS Lambda function with a Function URL, or a Cloudflare Worker. Any other host that can run Node.js 20+ also works.


1

Create the Relay Workflow Group

In Relay Dash, open Incidents in the left-hand navigation.

Select Workflow Groups, then Create Workflow Group.

Name the group. This guide uses food-safety.

Set the type to No Type.

Select the new group, choose Edit Membership, and add the users who should be called.

The group name is what the receiver will send in the groups array of the API payload.

2

Collect your Relay credentials

Value
Where to find it

subscriber_id

Relay Dash → Help → Diagnostic Logs → Server Details, listed under Subscriber

apikey

Relay Dash → Help → API Keys → create a key

3

Prove the Relay side works

Fire the alert by hand first:

A successful call returns HTTP/2 200 and a task ID:

Devices in food-safety should now be speaking the message every 30 seconds. Tap the talk button on one to acknowledge, or cancel it from the terminal:

4

Create a Mitti API token

The receiver uses a Mitti API token to read issues. You also use a token to register the webhook in Step 7. Mitti supports two kinds; for a shared, long-running integration, use a service user token.

  1. Log in to the Mitti web app.

  2. Click your organization name in the lower-left corner and select Integrations.

  3. Select the API tokens tab, then + Create API token.

  4. Name the token (for example Relay food safety alerts) and choose an inactivity expiry (31, 45, 60, or 180 days).

  5. Select the permission sets for the service user. Make sure Override permissions: Manage all data is included. Mitti requires this permission for a service user to receive webhook payloads, and it also lets the receiver read any issue.

  6. Select Create token, then copy the token and store it securely before closing the window. It is not shown again.

Creating a service user token requires the Platform management: Organization, Permissions, and Users permissions and a full seat. If you would rather use a user token, the user must have the Administrator permission, and user tokens expire after 30 days of inactivity.

Tokens also expire after a period of inactivity. Because the receiver calls the Mitti API every time an issue is created, a quiet organization could see a token lapse. Choose the longest inactivity window that fits your policy, and set a reminder to rotate it.

Set it aside as MITTI_API_TOKEN. For more detail see Mitti's Authentication guide.

5

Get the webhook signature secret

Mitti signs every webhook so your receiver can confirm it is genuine. Fetch your organization's signature secret:

The response contains the secret in a token field:

Set this aside as MITTI_WEBHOOK_SECRET.

6

Deploy the receiver

The receiver has two parts: a platform-neutral core (receiver.js) that holds all of the logic, and a small adapter for the platform you host on. The core requires Node.js 20 or later, because it uses the built-in fetch, Request, Response, and Web Crypto APIs.

The core: receiver.js

Use this file unchanged on every platform.

Settings

Every platform uses the same settings. Set them in the platform's configuration, not in source code.

Setting
Purpose

MITTI_WEBHOOK_SECRET

Signature secret from Step 5. Requests that do not match it are rejected.

MITTI_API_TOKEN

Mitti API token from Step 4.

RELAY_SUBSCRIBER_ID

Subscriber ID from Step 2.

RELAY_API_KEY

Relay API key from Step 2.

RELAY_GROUP

Workflow Group to alert. Defaults to food-safety.

FOOD_SAFETY_CATEGORIES

Comma-separated list of Mitti Issue categories that should trigger an alert. Matching ignores case. Defaults to Food safety.

The adapter for your platform

Mitti may deliver the same event more than once, and the receiver sends only one alert per issue. To do that across restarts and multiple instances, it needs a small persistent store. Each adapter below wires up the natural choice for its platform. Without a store the receiver falls back to memory, which protects only a single running instance and is not suitable for production.

This adapter uses the Node.js v4 programming model and stores de-duplication records in Azure Table Storage.

Create a Function App that runs a supported Node.js version on Linux (see Microsoft's Node.js developer reference for supported versions and project setup). Lay the project out like this:

host.json:

package.json:

src/functions/mitti.js:

Configure. In the Function App, open Settings → Environment variables and add the settings from the table above as app settings. For the three credentials, use Key Vault references rather than pasting the values.

Deploy. From the project folder:

Your webhook URL is:

De-duplication store. The adapter uses the Function App's own storage account (the AzureWebJobsStorage setting) and creates a table named mittiseen the first time it runs. Each alerted issue adds one small row, and rows older than 24 hours are ignored. Table Storage does not delete them automatically, so clear old rows occasionally if the volume matters to you. If your app uses identity-based storage and has no connection string, set SEEN_STORAGE_CONNECTION to a storage account connection string instead.

The trigger uses authLevel: 'anonymous' because Mitti authenticates itself with its HMAC signature, and the receiver rejects anything that fails the check. For a second layer, change it to 'function' and register the webhook URL with ?code=<function key> on the end.

Logs. Use Monitoring → Log stream, or Application Insights if you have it enabled.

This adapter handles a Lambda Function URL (payload format 2.0) and stores de-duplication records in DynamoDB.

1. Create the DynamoDB table. Create a table named mitti-seen with partition key pk (type String). Enable Time to Live on an attribute named expires.

2. Create the function. Create a Lambda function using the Node.js 22.x runtime and set the handler to lambda.handler. Upload a zip containing the two files below. The AWS SDK for JavaScript v3 is included in the Node.js runtime, so there is nothing to install.

lambda.js:

3. Configure. Add the settings from the table above as environment variables, plus SEEN_TABLE set to mitti-seen. Set the function timeout to 30 seconds. The default of 3 seconds is too short, because each delivery makes two outbound API calls. For the three credentials you can read them from AWS Secrets Manager instead of using plain environment variables if your policy requires it.

4. Allow table access. Attach a policy to the function's execution role that allows dynamodb:GetItem and dynamodb:PutItem on the mitti-seen table.

5. Create the Function URL. On the function's Configuration → Function URL page, create a URL with auth type NONE. Mitti cannot sign requests with AWS credentials, so the receiver authenticates Mitti with its HMAC signature instead. Your webhook URL is the function URL, which looks like:

AWS requires both lambda:InvokeFunctionUrl and lambda:InvokeFunction permissions to invoke a function URL. If you create the URL with infrastructure-as-code or the CLI rather than the console, make sure the function's resource-based policy grants both for public access.

De-duplication store. Each alerted issue adds one item to mitti-seen that expires after 24 hours. DynamoDB deletes expired items lazily, sometimes well after expiry, so the adapter also checks the expiry time itself.

Logs. Output goes to the function's CloudWatch log group.

This adapter runs as a Cloudflare Worker and stores de-duplication records in Workers KV.

Project files:

worker.js:

wrangler.toml:

Configure. Store the credentials as secrets:

De-duplication store. Create a KV namespace and add the binding it prints to wrangler.toml (the commented kv_namespaces block):

Deploy:

The URL it prints (for example https://mitti-relay-food-safety.<your-account>.workers.dev) is your webhook destination.

Logs. Run npx wrangler tail.

Hosting somewhere else? The core only needs a Request-like object (method, headers.get(), text()) and an object of settings. Write a short adapter for your platform that builds the request, calls handle(request, env), and returns the response, as the adapters above do. Read the raw request body for signature checking, and do not let your framework parse and re-serialize the JSON before it reaches the receiver.

Note the public HTTPS URL for your platform. It is the webhook destination in the next step.

7

Register the Mitti webhook

Register the receiver's URL from Step 6 for the Issue created event:

The response includes the new webhook_id and "enabled": true. To confirm the registration at any time, list your webhooks:

Webhooks are set up at the organization level. Any Issue created in the top-level organization triggers it, regardless of who created it. The receiver's category filter is what narrows this down to food safety.

8

Test it end to end

In the Mitti app, create a new Issue:

  1. Give it a title such as Walk-in cooler reading 52F.

  2. Set the category to Food safety.

  3. Set a site, if your organization uses sites. The site name is spoken in the alert.

  4. Save the issue.

Within a few seconds a device in your Workflow Group should speak:

Food safety alert at Store 12 Downtown. Walk-in cooler reading 52F. Please respond.

Tap the talk button to acknowledge. The device that accepts hears Accepted. You are responding to the food safety alert at Store 12 Downtown. and the other devices in the group stop alerting.

To confirm from the receiver side, check its logs (Log stream or Application Insights on Azure, CloudWatch on AWS, npx wrangler tail on Cloudflare). A successful run logs:

Then create a second Issue with a different category, such as Maintenance. No alert should sound, and the log shows the issue was ignored.


How the receiver behaves

Situation
Receiver response
What happens

Valid food safety issue

200

One Relay alert is sent and the issue is remembered.

Same issue delivered again

200

Ignored as a duplicate. No second alert.

Issue in a different category

200

Ignored. Mitti does not retry.

Any event other than Issue created

200

Ignored.

Signature missing or wrong

401

Rejected before any outbound call.

Mitti API or Relay API call fails

502

Mitti retries. The issue is not remembered, so the retry can still send the alert.

Mitti retries a failed delivery up to 4 times, 100 seconds apart, when the receiver returns a 4xx or 5xx response. Delivery is best-effort and events can arrive out of order, so the receiver is built to be safe to call repeatedly. That is why ignored events return 200: a 4xx for an issue you intentionally skip would only cause pointless retries.


Customizing the alert

Which issues page the team

The FOOD_SAFETY_CATEGORIES setting takes a comma-separated list, so one receiver can cover several categories:

Categories are matched by name, ignoring case. They must match the category names in your Mitti organization exactly (apart from case).

Different groups for different sites or categories

To route alerts to different Relay Workflow Groups, replace the groups: [env.RELAY_GROUP || 'food-safety'] line with a lookup based on issue.task?.site?.name or issue.category?.key. Each value must match a Workflow Group name (or URN) in Relay Dash.

Other Mitti events

The same receiver pattern works for other webhook events. For example, TRIGGER_EVENT_ACTION_CREATED covers new corrective actions, and TRIGGER_EVENT_INSPECTION_COMPLETED_STATUS covers completed inspections. Each event needs its own fetch-and-filter logic, because the webhook itself only carries identifiers. See Supported webhook trigger events.


Payload reference

Mitti webhook envelope

Every Mitti webhook uses the same outer structure. The receiver uses the fields marked below.

Field
Used for

webhook_id

Identifies the webhook registration.

event.event_types

List of event types. The receiver acts only on TRIGGER_EVENT_INCIDENT_CREATED.

event.date_triggered

When the event occurred.

resource.id

The ID of the issue. The receiver fetches the full issue with it.

resource.type

The kind of resource the event refers to.

Mitti fields used from Get Issue

The receiver calls GET https://api.mitti.com/tasks/v1/incident/{id} (the Get Issue endpoint) and reads:

Field
Used for

incident.category.key

Matched against FOOD_SAFETY_CATEGORIES.

incident.task.title

Spoken as the problem description.

incident.task.site.name

Spoken as the location, when the issue has a site.

In the Mitti API, Issues were previously called Incidents, so you will see incident in endpoint paths and response fields. They are the same thing.

Relay alert keys

notification and groups are required. Everything else is optional.

Key
Type
Default
Behavior

notification

string

—

Spoken on every device in the group via text-to-speech.

groups

array

—

Workflow Group names or URNs to alert.

quorum

integer

all devices must acknowledge

Cancels remaining alerts after this many acknowledgements. Set this to 1 for food safety calls.

on_ack

string

nothing spoken

Spoken on the device that acknowledged.

on_quorum

string

nothing spoken

Spoken on devices that had not yet acknowledged once quorum is met.

timeout

integer (sec)

300

Cancels remaining alerts after this long.

on_timeout

string

nothing spoken

Spoken on devices that never acknowledged, after timeout.

name

string

alerts

Controls serial/concurrent alerting behavior and appears in analytics events for correlation.

Leaving quorum at its default means the alert keeps sounding on every other device until all of them acknowledge. That is not what you want when one person takes the job. Set quorum: 1.

The receiver builds the Relay request body with JSON.stringify(), so a double quote, backslash, or newline in an issue title cannot produce invalid JSON. If you adapt this code to build the body by string concatenation instead, those characters will cause Relay to reject the request with a 400.


Troubleshooting

Start with the receiver's logs. Every delivery produces one log line or one JSON response.

Symptom
Likely cause and fix

No requests reach the receiver at all

The webhook is not registered, is disabled, or points at the wrong URL. List your webhooks (Step 7) and check enabled and url. Confirm the token that registered it had the permissions in Step 4.

Receiver returns 401 Invalid signature

The MITTI_WEBHOOK_SECRET is wrong or was regenerated, or the body was altered before verification. Fetch the secret again (Step 5), and make sure nothing parses and re-serializes the JSON before the signature check.

Receiver returns 502 Could not fetch issue

The Mitti API token is wrong, expired from inactivity, or its owner cannot access the issue. Check the status code in the log. Include Manage all data on a service user token so it can read every issue.

Log says Ignored: category ... is not a food safety category

The issue's category does not match FOOD_SAFETY_CATEGORIES. Compare against the exact category name in Mitti.

Receiver returns 502 Relay alert failed

Check the logged Relay status. 401 means the RelayApiKey header or key is wrong, and 404 usually means a wrong subscriber ID. Run the curl from Step 3 with the same values.

Log says Relay alert sent, but no device speaks

The alert was accepted, so check the Relay side. RELAY_GROUP must exactly match a Workflow Group name, and that group must have members whose devices are online.

The alert keeps repeating after someone started work

Alerts repeat every 30 seconds until acknowledged on a device or until timeout. Acknowledge on the device, or cancel with the DELETE call in Step 3.

Two alerts for one issue

The receiver is falling back to its in-memory store across multiple instances. Check that the platform's store is configured (Table Storage connection on Azure, SEEN_TABLE and table permissions on AWS, the SEEN KV binding on Cloudflare). The Azure and AWS adapters log a warning at startup when their store is missing.


Reference

Mitti

Relay