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:
Verifies that the request really came from Mitti, using the HMAC signature Mitti attaches to every webhook.
Fetches the issue from the Mitti API and checks that it is a food safety issue.
De-duplicates, because Mitti retries failed deliveries and may deliver the same event more than once.
Calls Relay with a message written for text-to-speech.
Prerequisites
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.
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.
Collect your Relay credentials
subscriber_id
Relay Dash → Help → Diagnostic Logs → Server Details, listed under Subscriber
apikey
Relay Dash → Help → API Keys → create a key
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.
Log in to the Mitti web app.
Click your organization name in the lower-left corner and select Integrations.
Select the API tokens tab, then + Create API token.
Name the token (for example
Relay food safety alerts) and choose an inactivity expiry (31, 45, 60, or 180 days).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.
Select Create token, then copy the token and store it securely before closing the window. It is not shown again.
Set it aside as MITTI_API_TOKEN. For more detail see Mitti's Authentication guide.
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.
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.
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:
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.
Note the public HTTPS URL for your platform. It is the webhook destination in the next step.
Test it end to end
In the Mitti app, create a new Issue:
Give it a title such as
Walk-in cooler reading 52F.Set the category to
Food safety.Set a site, if your organization uses sites. The site name is spoken in the alert.
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
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.
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:
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.
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.
Troubleshooting
Start with the receiver's logs. Every delivery produces one log line or one JSON response.
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.

