n8n-nodes-alertroster

n8n community node for AlertRoster, the CloudBedrock
call-out notification and escalation platform. Raise and drive incidents, read
and edit on-call schedules, act on shift handoffs and overrides, run
dead-man's-switch check-ins, and start workflows when incidents change state.

• Installation
• Credentials
• AlertRoster node
• AlertRoster Webhook Trigger node
• AlertRoster Trigger node (polling)
• Development

Installation

In n8n go to Settings → Community Nodes → Install and enter
n8n-nodes-alertroster. Or on a self-hosted instance:

cd ~/.n8n && npm install n8n-nodes-alertroster

Restart n8n. Three nodes appear: AlertRoster, AlertRoster Webhook
Trigger and AlertRoster Trigger.

Credentials

AlertRoster has two kinds of API credential, plus the signing secret of an
inbound webhook endpoint. Which one a node needs depends on the resource you
pick; the UI asks for exactly one.

AlertRoster Integration Key

For the Event and Incident resources. Paste one of:

A key is bound to one lane. The node checks the prefix against the operation
before calling the server and tells you which kind it wanted. Base URL defaults
to https://alertroster.com; set it to your own host for a self-hosted
instance. HTTPS is required except for localhost.

AlertRoster Webhook Secret

For the AlertRoster Webhook Trigger only: the signing secret of one
endpoint created on AlertRoster's Webhooks page. It is shown once there.

AlertRoster Responder

For everything else (Responder Incident, User, Schedule, Layer, Handoff,
Override, Check-In, Record, Source, Escalation Policy) and for the polling
Trigger node (the Webhook Trigger needs only the signing secret). Enter the
responder's email
and password. Responders normally sign in by magic link, so the password is
opt-in: set one under Settings in AlertRoster first. Leave Account ID blank
unless the email belongs to more than one account; the node then lists the
account ids in its error so you can pick one.

The node signs in, caches the 15-minute access token in workflow static data,
and signs in again when it expires or is rejected. Admin-only operations
(schedule and layer edits, overrides) need a responder with the admin role.

Operating notes

• Tier. Integration keys and account tokens are minted from the
  Duty of Care tier up (the gate is on minting, so a key that exists keeps
  working), and the scheduling layer (schedules, layers, overrides, handoffs)
  is available from the Lone Worker tier up. Below that the server answers
  403 with a plan refusal, which the node surfaces as the error message.
• Fresh versus stale tokens. The server lets a lapsed access token
  through for five more minutes on the incident list, incident get and
  timeline, acknowledge, resolve, reassign, silence and the user list, and on
  nothing else on the incident side. The check-in transitions (arm, extend,
  satisfy, cancel) and the briefing get the grace too; check-in create, edit,
  delete and the code routes, every schedule, layer, override and handoff
  write, and the search, report and context routes want a current token. The node signs
  in again a minute before its cached token expires, so this only shows up if
  a workflow is run against a session cache another host filled long ago.
• Rate limits. There is no rate limit on the incident list, so the
  trigger's poll interval is a cost choice, not a quota one. Password sign-in
  is throttled at 30 per 15 minutes per IP address, which is why the session
  is cached and shared across executions rather than logging in per item.

AlertRoster node

Every response is unwrapped to the object it describes; list operations emit
one item per record. Timestamps are ISO 8601 strings. Whole-number fields are
sent as integers because the server refuses strings.

Event (ark_async_ key)

Returns { status: "accepted", alert_id, dedup_key }. Ingest is asynchronous.

Incident (ark_sync_ key or art_ token)

Who holds an incident, and who is being asked

Every incident the node returns (Incident, Responder Incident, and the
trigger) carries assigned_to_user_id and paged_user_ids, and they answer
different questions. assigned_to_user_id is who holds the incident now. On a
source that escalates to a schedule it is set at trigger to whoever is on call,
set again on every escalation, and moved by Reassign. paged_user_ids is who is
being asked right now: everybody the current escalation-policy rung woke, in the
order the rung names them. It is [] on every incident that is not on a policy
rung, and Acknowledge, Reassign and Resolve all empty it.

A null assigned_to_user_id is not on its own a broadcast to the whole account.
On a triggered incident, read the pair together:

Once an incident is acknowledged or closed, paged_user_ids is always [] and
says nothing about who was paged; an acknowledgement over the Incident resource
or an expired ladder leaves assigned_to_user_id null as well, so the table
above does not apply to them.

Two related fields are easy to misread. acknowledged_by_user_id is history,
never overwritten, and stays null when the Incident resource acknowledged
over an integration key, because no responder did it; take "acknowledged" from
status. A policy rung firing changes paged_user_ids and escalation_rule_position
but not status, so the trigger does not fire for it; poll Get if a workflow
needs to follow the ladder.

Responder Incident

Get Search, Locate and Beacon need the subject's consent (409 consent_missing)
and an open incident (409 incident_closed). Photo URLs in subject.profile
are presigned and expire in minutes; every photograph carries taken_at and
age_days, and anything that shows the image should show its age.

The report link is a credential. Anyone holding the url that Share
Report and Get Report return can read the subject's photograph, description
and captured positions with no login. n8n keeps execution data, so a workflow
that handles it should send the link where it is needed (a text message, a
chat channel, an email to the search team) and not write it into logs or
sheets. The pattern that fits: on incident.triggered for a check-in incident,
Share Report and post the link; later, branch on Get Report's view_count to
chase a team that has not opened it; on incident.resolved, Withdraw Report.
A closed incident keeps answering the page with a stand-down notice until the
link is withdrawn or its seven days run out. The node can be used as an AI
agent tool; do not expose Share Report or Get Report that way, because the
link then lands in the model's context and transcript. These three
operations, like Get Search, Locate and Beacon, need a current access token;
the node signs in afresh before its cached token expires, so nothing extra is
required.

User

Schedule

Layer (admin except Get Many)

Handoff

Override

Check-In

Check-ins belong to the signed-in responder; the account must have check-ins
enabled.

Arm, Extend, Satisfy and Cancel accept an optional Location (latitude,
longitude, accuracy, fix time) and an optional Details object with the same
fields as Set Details. The server stores either only if the responder has
opted in, never fails the transition over them, and never reports whether it
kept them. Read the check-in back to see what it holds.

A briefing is not advice. It reports what the sources say and when they
said it. Nothing in it says a trip is safe, and it is never a reason a
check-in was not armed or an escalation did not run. severity and the text
are the source's own words. "Nothing reported" and "the sources could not be
reached" are different answers: branch on complete and each source's
answered before telling anyone that all is quiet. A source that is down
never fails the request; it is reported inside sources.

Source (admin, read-only)

Sources are edited on the Sources page. The id here is what Incident →
Create's Source ID takes with an art_ token, and last_used_at on a
key is how a workflow spots a monitor that has gone quiet.

Escalation Policy (admin, read-only)

A coverage audit is Source → Get Many joined to Escalation Policy → Get on
each escalation_policy_id: any source whose ladder's first rung reports
unresolved is one whose next incident pages nobody by name. Run it on a
schedule with At set to the next weekend night.

Dropdowns. Every Schedule ID field, on the Schedule resource itself and
on Layer, Override, Handoff and Check-In, is a dropdown filled from the
responder credential, and still takes an expression. Source ID on Incident → Create stays a plain
field: that resource runs on an integration key, which cannot list sources.

Record

The incident record over a date range, for the manager's weekly "who did not
answer, and how fast did the rest answer" and the compliance folder's monthly
export. Admin role, and the API tier (Duty of Care). From and To are
dates, taken as whole days in UTC at both ends, so what a person looked at on
the records page and what a workflow fetched are the same period; both are
required, and a range longer than 366 days is refused. Incidents are counted
by when they were raised. These routes need a current access token.

Ack-latency report

Every station keeps only 24 hours of history, and a phone shows one incident
at a time; the question "who did not answer last month" is answered here. On
a Schedule Trigger (weekly), Record → Get Incidents with Return All for the
last seven days, then a Code node per item. Skip rows with resolved_at
null (still open). For the rest, acknowledged_at - triggered_at in seconds
is the ack latency, status === 'expired' means nobody answered,
acknowledged_at set with acknowledged_by_user_id null means a ticket
system acknowledged it over the Incident resource, and
escalation_rule_position is how far up the ladder it went. Append the rows
to a Google Sheet or post the Record → Get Coverage object to a channel as
the summary; ack_seconds_median and unrostered_pages are the two numbers
a manager reads first. For the compliance folder, Record → Export with
timeline_csv on a monthly schedule into a Google Drive or S3 node.

AlertRoster Webhook Trigger node

AlertRoster sends signed webhooks when an incident changes, and this node
receives them: no polling, no responder login, and nothing missed between
polls. Use it wherever n8n has a public URL; the polling trigger below is the
fallback.

Setup. Add the node, activate the workflow, and copy its Production
URL. On AlertRoster's Webhooks page (admin, Duty of Care tier) create an
endpoint with that URL and, unless you want fewer, no event filter (an
endpoint subscribed to nothing receives every event, including kinds added
later). The signing secret is shown exactly once there: paste it into an
AlertRoster Webhook Secret credential. Then use Send a test event on
that page: the delivery log shows a 200 (the node answers ignored: test
and starts nothing), and a wrong secret shows as a refused 401 with the
reason in words. Lost secrets are rotated there, not recovered.

Each item is { event, incident, event_id, created_at, account_id, delivery_attempt }: the same event and incident the polling trigger
emits, so the two are interchangeable downstream. incident is the full
incident object rendered at send time: a retried incident.triggered
can arrive with status: resolved, and both are true, so treat each item as
an upsert keyed on incident.id and read history from Responder Incident →
Get Timeline rather than from the sequence of webhooks.

What the node does with each delivery, before anything runs:

• verifies x-alertroster-signature (t=…,v1=…, HMAC-SHA256 over the raw
  bytes with the secret) and rejects a signature more than five minutes from
  its clock; a failure answers 401, which AlertRoster records as refused
  and does not retry, so a rotated or mistyped secret is visible on the
  Webhooks page;
• answers 200 and starts nothing for an event kind it was not asked for, a
  webhook.test, an incident the Duress Only filter drops, or a retry of an
  event id it accepted in the last 24 hours (AlertRoster retries for about
  eleven hours on a timeout, with the same id);
• starts the workflow and answers 200 straight away for everything else.

The duplicate memory lives in the workflow's static data and is best effort
in two ways: a retry that lands while a long execution is still running,
after n8n's answer was lost in transit, can run twice; and the memory keeps
the newest 2,000 ids, so under more than that many events in a day a retry
of an older one runs again. Both are one more reason to upsert on
incident.id.

AlertRoster Trigger node (polling)

The fallback for an n8n that cannot receive webhooks. It polls with the
Responder credential. Pick the events to watch:

Each item is { event, incident }. The events other than Triggered and
Resolved are read off the fields of the open list between two polls, so a
transition that happens and is undone inside one interval (a silence that
lapses, a reassignment that is acknowledged) is reported as whatever the
incident looks like at the next poll, and one poll can emit several events
for one incident (a reassignment and a silence together). Escalation versus
reassignment is decided by the clock: a moved ack window whose previous
deadline had already passed is an escalation, one moved before its deadline is
a reassignment. On first activation the node records what is already open and
emits nothing. A manual test run shows the current open incidents as Triggered
or Acknowledged samples, subject to the event selection, without changing
that state. Set the poll interval in the node; one request per poll plus one
per incident that closed.

Duress. Every incident carries duress, true when a check-in was
satisfied with the duress code: the person is signalling under coercion. The
incident is paged to the rest of the roster as any other, but it is withheld
from the subject's own devices and list, so a trigger running on the subject's
own responder credential never sees it. A workflow should branch on duress
before anything else (no call back to the subject). Turn on Duress Only to
make a trigger fire for those incidents alone.

Upgrading from a release before these events existed: the first poll after
the upgrade names only status transitions for incidents that were already
open, then carries the full snapshot from there.

Recipes

A desktop station as an n8n webhook

The AlertRoster desktop station keeps its local outputs (siren relays, screen
takeover, commands) on its own receiver service, and one of the output kinds
is webhook: the station POSTs JSON to a URL when an alert starts paging and
again when it stops. Pointing that at an n8n Webhook node makes n8n the
station's logic for anything beyond a relay, with no AlertRoster server
change, and it works whether the alert came down from the cloud or was raised
on the LAN. This is where a Slack post, a PLC call or a log line belongs.

1. In n8n add a Webhook node, method POST, and copy its URL (the production
   URL once the workflow is active).
2. On the station, Outputs → add an output of kind Webhook with that URL.
3. Branch on {{ $json.body.state }}: fired when an alert has started
   paging, cleared when it was acknowledged, resolved or expired. The same
   value arrives in the X-AlertRoster-State header.

The body is:

{
  "event": "<output event name>",
  "state": "fired",
  "output": { "id": "…", "name": "Dispatch Slack" },
  "alert": {
    "id": "…", "status": "triggered", "urgency": "high",
    "title": "…", "detail": null, "dedup_key": null,
    "source": { … }, "triggered_at": "…", "ack_timeout_seconds": 300,
    "expires_at": "…", "acknowledged_at": null, "acknowledged_by": null,
    "resolved_at": null, "emergency": true, "available_actions": [ … ],
    "cloud": { "incident_id": "…", "status": "…", "assigned_to": "…", "duress": false, … }
  }
}

alert is the station's own alert object, not the cloud incident. When the
alert mirrors a cloud incident, alert.cloud.incident_id is the incident's
id, and a workflow that wants the authoritative record passes it to
Responder Incident → Get (or Get Search) on this node;
alert.cloud is null for an alert raised on the LAN that never reached the
cloud. The station retries a POST twice on a transport error or a 5xx, one
second apart, and does not retry a 4xx, so answer quickly (n8n's default
"respond immediately" is right) and do the work after responding.

The POST is not signed: anyone who can reach the URL can send one. Keep the
webhook on the LAN or behind a tunnel that only the station can use, and do
not have the workflow act on fired alone for anything that costs money or
wakes people; confirm against the cloud incident first. Signed POSTs are
tracked as alertroster-desktop #121.

Development

npm install --ignore-scripts   # isolated-vm (via n8n-workflow) need not build
npm run build                  # tsc + icon copy into dist/
npm run lint
npm run check:coverage         # routes called vs the published OpenAPI spec
npm run dev                    # tsc --watch

check:coverage fetches AlertRoster's OpenAPI document and fails when the
API has an operation this node neither implements nor excuses in
scripts/openapi-coverage-allowlist.json, or when the node calls a route the
API no longer documents. The allowlist is the list of server surface the node
deliberately lacks, each entry with its reason. CI (.github/workflows/ci.yml)
runs build, lint and this check on every pull request and on pushes to main;
a spec that cannot be fetched is a CI warning, drift is a failure.

To try it locally, link the package into your n8n custom directory:

npm run build && npm link
cd ~/.n8n/custom && npm link n8n-nodes-alertroster

Design notes live in docs/superpowers/specs/. Issues and pull requests:
https://github.com/CloudBedrock/n8n-nodes-alertroster.

License

MIT © CloudBedrock