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

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:

  1. Verifies each request really came from MaintainX by checking its HMAC signature.

  2. Classifies the event: what happened and how urgent it is. For example, a high-priority work order is urgent, a medium-priority one is a notice, and a low-priority one is ignored.

  3. 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.

  4. 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.

Alerts vs. broadcasts. An alert repeats on the device every 30 seconds until someone presses the talk button to acknowledge it, or until it times out. A broadcast plays once and needs no acknowledgement. Save alerts for work that needs someone to own it.

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:

Host
Good for
Included config

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

Side
Requirement

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.

Hosting

An account on Replit, Render, or Heroku. All three need a paid plan for an always-on service.


Set up the bridge

1

Create your Relay Workflow Groups

Alerts and broadcasts are sent to Workflow Groups. Create a group for each audience that should hear maintenance events.

  1. In Relay Dash, open Incidents from the left menu.

  2. Select Workflow Groups → Create Workflow Group.

  3. Enter a name and select No Type.

  4. Select the group, then use Edit Membership to add users.

A typical setup has a few groups that routes combine:

Workflow Group
Who's in it

maintenance

Technicians on the floor

supervisors

Supervisors who need to know about urgent work

safety

Safety team, for escalations

2

Collect your Relay credentials

Value
Where to find it

API key

Relay Dash → Help → API Keys

Subscriber ID

Relay Dash → Help → Diagnostic Logs → Server Details → Subscriber

Before deploying anything, check them with a broadcast:

If the devices in that group speak the message, you're ready.

3

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.

4

Deploy the bridge

Every option prompts for the same settings:

Setting
Required
Value

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.

  1. 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.

  2. Open Secrets and add each setting from the table above.

  3. Select Publish. The repo's .replit selects 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.

  4. Once it's published, copy the app's URL, e.g. https://maintainx-relay-bridge.replit.app.

  1. Select Deploy to Render:

    Deploy to Render

    Render reads render.yaml and sets up a Blueprint with a Node web service, npm ci / npm start, and a health check on /health.

  2. Enter a value for each setting from the table above when prompted.

  3. Select Deploy Blueprint.

  4. 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.

  1. Select Deploy to Heroku:

    Deploy to Heroku

    Heroku reads app.json and shows a form with every setting. It pre-fills RELAY_ROUTES with the defaults and sets DRY_RUN to true.

  2. Choose an app name and region, fill in the settings from the table above, and select Deploy app.

  3. 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:

5

Register the webhook in MaintainX

  1. In MaintainX, go to Settings → Integrations → Webhooks and select + New Webhook.

  2. In Trigger Webhook On, choose an event, such as New Work Order.

  3. In Endpoint, paste your webhook URL and save.

  4. Select Copy secret, then replace placeholder in MAINTAINX_WEBHOOK_SECRET with it:

Host
Where to update 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.

Each MaintainX webhook has its own secret, and the bridge accepts one. To handle several events, such as New Work Order, Work Order Status Change, and Work Order Overdue, deploy one bridge per event or extend verifySignature in src/bridge.js to accept a list of secrets.

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.

6

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:

Host
Logs

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:

What you want
Change

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.

Working with an AI agent? Replit Agent, Claude Code, Cursor, and similar tools all work well on this repo. Give them the rule that matters most: event rules return a route name, never a group. Run npm test afterwards. The tests include a check that MaintainX assignment data doesn't change the audience.

Alert route options

Field
Default
Behavior

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

Field
Type
Notes

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 200 once the signature checks out.


Troubleshooting

Symptom
Likely cause

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

Last updated