> For the complete documentation index, see [llms.txt](https://developer.relaypro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.relaypro.com/integrations/maintainx-alerts.md).

# MaintainX Alerts

## Overview

[MaintainX](https://www.getmaintainx.com/) 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**](https://github.com/relaypro/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.

```mermaid
flowchart LR
    MX[MaintainX] -- "signed webhook (POST)" --> B[maintainx-relay-bridge]
    B -- "verify signature,<br/>classify event" --> B
    B -- "Relay route:<br/>alert or broadcast" --> R[Relay API]
    R -- "text-to-speech" --> G1[Workflow Group A]
    R -- "text-to-speech" --> G2[Workflow Group B]
```

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.&#x20;

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

{% hint style="warning" %}
Avoid routing on MaintainX assignment data (`teamIds`, `assigneeIds`, `locationId`, `categories`). It ties delivery to how work orders happen to be filled in, and bypasses what Relay knows about who is actually available.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

### 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:

<table><thead><tr><th width="140">Host</th><th>Good for</th><th>Included config</th></tr></thead><tbody><tr><td><strong>Replit</strong></td><td>Teams that want an all-in-one workspace: the code, an AI agent to customize it, secrets, and hosting in one place.</td><td><code>.replit</code></td></tr><tr><td><strong>Render</strong></td><td>One-click deploy from GitHub, with automatic redeploys when you push.</td><td><code>render.yaml</code></td></tr><tr><td><strong>Heroku</strong></td><td>Teams already on Heroku. One-click deploy that prompts for each setting.</td><td><code>app.json</code></td></tr></tbody></table>

The repo also includes a `Dockerfile`, so it runs anywhere that runs Node.js 20 or a container.

***

## Prerequisites

<table><thead><tr><th width="180">Side</th><th>Requirement</th></tr></thead><tbody><tr><td><strong>Relay</strong></td><td>A Relay account on the <strong>Enterprise</strong> plan (needed for API keys), access to <strong>Relay Dash</strong>, and at least one Relay device to test with.</td></tr><tr><td><strong>MaintainX</strong></td><td>Admin access to create webhooks (<strong>Settings → Integrations → Webhooks</strong>). <em>Optional:</em> a MaintainX API key to add work order titles and location names to alerts. MaintainX API access needs a Premium or Enterprise plan.</td></tr><tr><td><strong>Hosting</strong></td><td>An account on <a href="https://replit.com/">Replit</a>, <a href="https://render.com/">Render</a>, or <a href="https://www.heroku.com/">Heroku</a>. All three need a paid plan for an always-on service.</td></tr></tbody></table>

***

## Set up the bridge

{% stepper %}
{% step %}

## 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                   |
| {% endstep %}  |                                                |

{% step %}

## 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:

```sh
export RELAY_SUBSCRIBER_ID=your-subscriber-id
export RELAY_API_KEY=your-api-key

curl -X POST "https://api.relaypro.com/subscribers/$RELAY_SUBSCRIBER_ID/api/v1/broadcasts" \
  -H "Authorization: RelayApiKey $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notification": "MaintainX integration test.", "groups": ["maintenance"]}'
```

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

{% hint style="warning" %}
The `Authorization` header must include the literal prefix `RelayApiKey`, followed by a space and then your key.
{% endhint %}
{% endstep %}

{% step %}

## 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:

```json
{
  "urgent": {
    "mode": "alert",
    "groups": ["maintenance", "supervisors"],
    "timeout": 300,
    "quorum": 1,
    "on_quorum": "Someone else has this work order."
  },
  "notice": {
    "mode": "broadcast",
    "groups": ["maintenance"]
  }
}
```

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`.
{% endstep %}

{% step %}

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

{% tabs %}
{% tab title="Replit" %}

1. Open [**replit.com/github.com/relaypro/maintainx-relay-bridge**](https://replit.com/github.com/relaypro/maintainx-relay-bridge), or go to [replit.com/import](https://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`.

{% hint style="success" %}
**Customize with Replit Agent.** After importing, you can ask Agent to change the bridge in plain language, for example: *"Add a `critical` route and send `WORK_ORDER_OVERDUE` events to it."* See [Customizing](#customizing) for the rules to give it.
{% endhint %}
{% endtab %}

{% tab title="Render" %}

1. Select **Deploy to Render**:

   [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/relaypro/maintainx-relay-bridge)

   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.

{% hint style="warning" %}
`render.yaml` uses the **Starter** instance type. Render's free instances sleep when idle, and a webhook that wakes one can take longer than the 10 seconds MaintainX waits.
{% endhint %}
{% endtab %}

{% tab title="Heroku" %}

1. Select **Deploy to Heroku**:

   [![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/relaypro/maintainx-relay-bridge)

   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.
{% endtab %}
{% endtabs %}

Open `https://<your-host>/health`. It should return `{"ok":true}`. Your webhook URL is:

```
https://<your-host>/webhooks/maintainx
```

{% endstep %}

{% step %}

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

{% hint style="info" %}
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.
{% endhint %}

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`:

```json
{
  "type": "WORK_ORDER_STATUS_CHANGE",
  "url": "https://<your-host>/webhooks/maintainx",
  "filters": { "oneOfStatuses": ["ON_HOLD"] }
}
```

Get the secret with `GET /v1/subscriptions/{id}/secret`.
{% endstep %}

{% step %}

## 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:

```sh
git clone https://github.com/relaypro/maintainx-relay-bridge && cd maintainx-relay-bridge && npm install

MAINTAINX_WEBHOOK_SECRET=your-secret \
WEBHOOK_URL=https://<your-host>/webhooks/maintainx \
npm run test:webhook            # or: npm run test:webhook -- on-hold | overdue
```

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.
{% endstep %}
{% endstepper %}

***

## 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`](https://github.com/relaypro/maintainx-relay-bridge/blob/main/src/bridge.js)) decide which route an event belongs to, based only on what happened:

```js
const PRIORITY_ROUTE = { HIGH: "urgent", MEDIUM: "notice", LOW: null, NONE: null };
const STATUS_ROUTE = { ON_HOLD: "notice", DONE: null, OPEN: null, IN_PROGRESS: null };
// WORK_ORDER_OVERDUE -> "urgent"
```

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

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="success" %}
**Write for the ear.** Lead with what happened and where: "High priority work order: compressor 3 leaking oil, building B." Avoid IDs, URLs, and abbreviations that text-to-speech reads badly. The bridge cuts messages off at 600 characters.
{% endhint %}

### 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](https://developer.relaypro.com/docs/relay-alerts-api/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

{% hint style="danger" %}
**Always verify the signature.** The webhook URL is public. Without verification, anyone who finds it can make your devices speak.
{% endhint %}

* **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](https://developer.relaypro.com/docs/relay-events-api) to see who acknowledged, then post a comment on the work order through the MaintainX API.

## Reference

### Template

* [maintainx-relay-bridge on GitHub](https://github.com/relaypro/maintainx-relay-bridge)

### Relay

* [Triggering an Alert](https://developer.relaypro.com/docs/relay-alerts-api/triggering-an-alert)
* [Customizing Your Alerts](https://developer.relaypro.com/docs/relay-alerts-api/customizing-your-alerts)
* [Advanced Configuration](https://developer.relaypro.com/docs/relay-alerts-api/advanced-configuration)
* [Broadcasts](https://developer.relaypro.com/docs/relay-broadcasts-api)

### MaintainX

* [Webhooks guide](https://help.getmaintainx.com/build/webhooks)
* [REST API reference](https://api.getmaintainx.com/v1/docs)

### Hosting

* Replit: [Import from GitHub](https://docs.replit.com/build/import-from-providers) · [Secrets](https://docs.replit.com/core-concepts/project-editor/app-setup/secrets) · [Deployment types](https://docs.replit.com/features/publishing/deployment-types)
* Render: [Blueprints](https://render.com/docs/infrastructure-as-code) · [Environment variables](https://render.com/docs/configure-environment-variables)
* Heroku: [Heroku Button](https://devcenter.heroku.com/articles/heroku-button) · [Config Vars](https://devcenter.heroku.com/articles/config-vars) · [Deploying Node.js](https://devcenter.heroku.com/articles/deploying-nodejs)
