MaintainX Alerts
Overview
MaintainX is a maintenance and work order platform. When something happens in MaintainX, such as a new high-priority work order, a job put on hold, or a work order going overdue, it can send a webhook: an HTTP POST to a URL you choose.
The maintainx-relay-bridge template receives those webhooks and turns them into Relay alerts and broadcasts. Technicians hear the work order on their Relay device right away, and alerts keep repeating until someone acknowledges them.
The bridge does four things:
Verifies each request really came from MaintainX by checking its HMAC signature.
Classifies the event: what happened and how urgent it is. For example, a high-priority work order is
urgent, a medium-priority one is anotice, and a low-priority one is ignored.Hands it to a Relay route. A route is defined on the Relay side. It says how the event is delivered (alert or broadcast) and which Relay Workflow Groups hear it. One route can reach several groups at once.
Speaks a short message on the devices through the Relay Alerts or Broadcasts API.
Who hears it is a Relay decision
MaintainX knows what needs doing. Relay knows who is on shift, on the floor, and able to respond.
MaintainX supplies the event: what happened, its priority, and the details to speak.
Relay owns the audience: routes and Workflow Groups are configured for Relay, not derived from MaintainX teams, locations, or categories.
Where to run it
The bridge is a small Node.js service with ready-to-use configuration for three hosts. Pick whichever fits your team:
Replit
Teams that want an all-in-one workspace: the code, an AI agent to customize it, secrets, and hosting in one place.
.replit
Render
One-click deploy from GitHub, with automatic redeploys when you push.
render.yaml
Heroku
Teams already on Heroku. One-click deploy that prompts for each setting.
app.json
The repo also includes a Dockerfile, so it runs anywhere that runs Node.js 20 or a container.
Prerequisites
Relay
A Relay account on the Enterprise plan (needed for API keys), access to Relay Dash, and at least one Relay device to test with.
MaintainX
Admin access to create webhooks (Settings → Integrations → Webhooks). Optional: a MaintainX API key to add work order titles and location names to alerts. MaintainX API access needs a Premium or Enterprise plan.
Set up the bridge
Create your Relay Workflow Groups
Alerts and broadcasts are sent to Workflow Groups. Create a group for each audience that should hear maintenance events.
In Relay Dash, open Incidents from the left menu.
Select Workflow Groups → Create Workflow Group.
Enter a name and select No Type.
Select the group, then use Edit Membership to add users.
A typical setup has a few groups that routes combine:
maintenance
Technicians on the floor
supervisors
Supervisors who need to know about urgent work
safety
Safety team, for escalations
Define your Relay routes
A route names a delivery mode and the Workflow Groups it reaches. The bridge ships with two routes, urgent and notice. Decide which groups each one should reach. In this example, urgent work goes to technicians and shift leads together, and the first person to acknowledge it takes it for everyone:
You'll paste this, as a single line, into the RELAY_ROUTES setting in the next step. Group names must match your Workflow Groups exactly. If you leave RELAY_ROUTES unset, both routes go to maintenance.
Deploy the bridge
Every option prompts for the same settings:
RELAY_API_KEY
Yes
From step 2
RELAY_SUBSCRIBER_ID
Yes
From step 2
MAINTAINX_WEBHOOK_SECRET
Yes
Enter placeholder for now. You'll get the real value in step 5.
RELAY_ROUTES
No
Your routes from step 3, as one line of JSON
MAINTAINX_API_KEY
No
MaintainX Settings → Integrations → API Keys. Adds titles and locations to spoken alerts.
DRY_RUN
No
Leave at true while testing. The bridge logs what it would send to Relay instead of sending it.
Open replit.com/github.com/relaypro/maintainx-relay-bridge, or go to replit.com/import, choose GitHub, and select the repo. Replit installs dependencies and reads the run command from
.replit.Open Secrets and add each setting from the table above.
Select Publish. The repo's
.replitselects a Reserved VM, which stays on to receive webhooks. You can switch to Autoscale, which costs less but adds a short cold start after idle periods.Once it's published, copy the app's URL, e.g.
https://maintainx-relay-bridge.replit.app.
Enter a value for each setting from the table above when prompted.
Select Deploy Blueprint.
Once the service is live, copy its URL, e.g.
https://maintainx-relay-bridge.onrender.com.
To fork the repo first and deploy from your fork, go to New → Blueprint in the Render Dashboard and connect your fork instead. Render then redeploys every time you push.
Choose an app name and region, fill in the settings from the table above, and select Deploy app.
When the build finishes, select View and copy the URL, e.g.
https://maintainx-relay-bridge.herokuapp.com. Newer Heroku apps add a random suffix to the hostname, so copy it exactly.
Heroku detects Node.js from package.json and runs npm start. No Procfile is needed.
Open https://<your-host>/health. It should return {"ok":true}. Your webhook URL is:
Register the webhook in MaintainX
In MaintainX, go to Settings → Integrations → Webhooks and select + New Webhook.
In Trigger Webhook On, choose an event, such as New Work Order.
In Endpoint, paste your webhook URL and save.
Select Copy secret, then replace
placeholderinMAINTAINX_WEBHOOK_SECRETwith it:
Replit
Secrets, then Publish again so the deployment picks up the change
Render
Service → Environment. Saving redeploys the service.
Heroku
App → Settings → Reveal Config Vars. Saving restarts the app.
You can also create webhooks through the MaintainX REST API (POST https://api.getmaintainx.com/v1/subscriptions), which can filter server-side. For example, this subscription fires only when a work order moves to ON_HOLD:
Get the secret with GET /v1/subscriptions/{id}/secret.
Test end to end and go live
1. Send a signed test event. With DRY_RUN still true, clone the repo and run its test script against your deployment, using the same secret:
You should see HTTP 200 {"status":"sent","route":"urgent"}. The host's logs should show the Relay request it would have sent, with every group on the urgent route:
Replit
Publishing → Logs
Render
Service → Logs
Heroku
More → View logs
If you change the secret, you'll get 401 instead.
2. Go live. Set DRY_RUN to false and redeploy or restart. Then create a High priority work order in MaintainX. Devices in every group on the urgent route should speak the alert. Press the talk button to acknowledge it, and the alert stops repeating.
Customizing
Routing has two layers, and each one changes in its own place:
Relay routes (
RELAY_ROUTES) decide who hears an event and how. Change them in your host's settings, the same way you updated the secret in step 5. No code change is needed.Event rules (the Event rules section of
src/bridge.js) decide which route an event belongs to, based only on what happened:
Urgent work also reaches the safety team
Add "safety" to RELAY_ROUTES.urgent.groups
Shift leads hear notices too
Add "supervisors" to RELAY_ROUTES.notice.groups
First responder takes it, across all groups
"quorum": 1 on the route
Add a third tier, such as critical for overdue work
Add a critical route to RELAY_ROUTES, then return route: "critical" for WORK_ORDER_OVERDUE in classify()
Medium-priority work orders should also need acknowledgement
PRIORITY_ROUTE.MEDIUM = "urgent"
Announce completed work
STATUS_ROUTE.DONE = "notice"
Handle another event
Add a case to classify(). Asset events such as ASSET_STATUS_CHANGE work the same way.
Change what's spoken
Edit the text: templates in classify(). Keep them short, because they're read aloud.
Code changes deploy the usual way for your host. On Replit, edit in the workspace and Publish again. On Render and Heroku, push to the connected GitHub repo, or redeploy from the dashboard.
Alert route options
timeout
300
Seconds before unacknowledged alerts are cancelled
on_ack
"Thanks, work order acknowledged."
Spoken on the device that acknowledged
quorum
all devices
Number of acknowledgements needed to cancel the alert for everyone else. Use 1 for "first responder takes it".
on_quorum
silent
Spoken on the remaining devices once the quorum is met
on_timeout
"No one acknowledged this work order."
Spoken on unacknowledged devices when the timeout hits
The bridge sets the Relay name field to maintainx-<route>, so analytics show which route fired. See Customizing Your Alerts for details.
Payload reference
These are the fields you'll most often use for classification and spoken text. Assignment fields such as teamIds and locationId are listed for completeness. Use them in the spoken message, not to pick an audience. Every MaintainX webhook includes eventType, so a single endpoint can handle every event type.
NEW_WORK_ORDER
eventType
string
"NEW_WORK_ORDER"
workOrderId
number
Global work order ID
orgId
number
MaintainX organization
occurredAt
ISO date-time
When the event happened
userId
number
Who created it. Absent when an automation or schedule created it.
newWorkOrder.title
string
newWorkOrder.priority
string
NONE, LOW, MEDIUM, HIGH
newWorkOrder.dueDate
ISO date-time
newWorkOrder.locationId / assetId
number
Look up names via GET /v1/locations/{id} and GET /v1/assets/{id}
newWorkOrder.teamIds / assigneeIds
number[]
Assignment in MaintainX
newWorkOrder.categories
object[]
{ id, name }
WORK_ORDER_STATUS_CHANGE
Has the same identifiers and newWorkOrder object, plus oldStatus, newStatus (OPEN, IN_PROGRESS, ON_HOLD, DONE), and optionally oldSubStatus / newSubStatus (CANCELED, SKIPPED).
WORK_ORDER_OVERDUE
Has only eventType, workOrderId, orgId, dueDate, and occurredAt. To speak a title or location, the bridge looks the work order up with MAINTAINX_API_KEY.
For the full event catalog, see the MaintainX API reference under Subscriptions & Webhooks.
Security notes
Reject stale timestamps. The bridge accepts signatures within 5 minutes, as MaintainX recommends, which blocks replay attacks.
Keep secrets in your host's secret store (Replit Secrets, Render Environment, Heroku Config Vars), not in code, in the repo, or in chats with an AI agent.
Answer quickly. MaintainX times out after 10 seconds and may delete a webhook that keeps failing, emailing your account when it does. The bridge caps outbound calls at 5 seconds and always replies
200once the signature checks out.
Troubleshooting
App won't start: Missing required environment variables
A required setting is empty. RELAY_API_KEY is optional only while DRY_RUN=true.
App won't start: RELAY_ROUTES.<name> needs…
A route is missing groups, has an empty list, or has a mode other than alert or broadcast. Also check that the JSON is on one line.
401 invalid signature on real events
MAINTAINX_WEBHOOK_SECRET is still placeholder, belongs to a different webhook, or wasn't picked up (republish on Replit)
MaintainX deliveries time out
The instance is asleep. Use Replit Reserved VM, Render Starter or higher, or an always-on Heroku dyno.
{"status":"ignored"}
Your event rules intentionally skipped the event, e.g. a low-priority work order
{"status":"no_route"}
An event rule returned a route name that isn't in RELAY_ROUTES
relay_error with HTTP 401 in logs
Wrong Relay API key
relay_error with HTTP 404
Wrong subscriber ID
Relay accepts the request but no device speaks
A group name in the route doesn't match a Workflow Group exactly, or the group has no members
Alerts arrive twice
Two webhooks are subscribed to the same event, or the bridge runs on several instances (duplicates are tracked per instance)
Overdue alerts say "number 12345"
MAINTAINX_API_KEY isn't set, or the plan doesn't include API access
Going further
Write acknowledgements back to MaintainX. Use the Relay Events API to see who acknowledged, then post a comment on the work order through the MaintainX API.
Reference
Template
Relay
MaintainX
Hosting
Replit: Import from GitHub · Secrets · Deployment types
Render: Blueprints · Environment variables
Heroku: Heroku Button · Config Vars · Deploying Node.js
Last updated

