ServiceNow

ServiceNow can push incident creates and updates to StatusDashboard through a Business Rule on the Incident table. When an incident is inserted or updated in ServiceNow, your rule builds a signed JSON payload and POSTs it to the inbound webhook endpoint. StatusDashboard opens or advances the matching incident on your status dashboards and sends subscriber notifications when configured.

Configure a Business Rule on the Incident table in ServiceNow (and any supporting Script Includes) using the patterns below. All mapping lives in ServiceNow: which CMDB services map to which StatusDashboard components, how ServiceNow State maps to workflow phases, and how Impact maps to severity labels.

For payload fields, signing, and webhook logs, see Inbound webhooks. For component and workflow configuration, see Components and Workflows.

How it works

The integration is a one-way push from ServiceNow to StatusDashboard:

1. A ServiceNow Business Rule runs after insert or after update on Incident [incident].
2. Your script reads the incident record (state, impact, descriptions, affected services).
3. Your script maps ServiceNow values to StatusDashboard component IDs, severity labels, and workflow phase labels using dictionaries you maintain in the script.
4. Your script signs the JSON body with your inbound webhook signing secret and POSTs to https://api.statusdashboard.com/public/webhooks/inbound.
5. StatusDashboard validates the signature, queues the payload, and creates or updates an incident event.

sequenceDiagram
  participant SN as ServiceNow Incident
  participant BR as Business Rule
  participant SD as StatusDashboard Inbound Webhook
  participant SP as Status Dashboard

  SN->>BR: Insert or update
  BR->>BR: Map CMDB services to componentIds
  BR->>BR: Map State and Impact
  BR->>SD: Signed POST (trigger or update)
  SD->>SP: Create or advance incident

Before you begin

Confirm the following on both sides before writing the Business Rule.

StatusDashboard

ServiceNow

Step 1 — Create an inbound webhook signing key

1. Open Inbound webhooks in the admin console.
2. Click Create key and copy the Key ID (for example wk_a1b2c3d4e5f6a7b8) and Signing Secret.
3. Store both values in ServiceNow where your integration script can read them.

The signing secret cannot be retrieved after the creation dialog closes. If it is lost, revoke the old key and create a new one.

See Authentication for the HMAC-SHA256 header format (X-SD-Key-Id, X-SD-Signature).

Step 2 — Collect StatusDashboard component IDs

Each incident webhook must include at least one StatusDashboard component UUID in componentIds.

1. List your organization's components with GET /app/components (see List components), or export IDs during initial setup.
2. Record the UUID next to each ServiceNow service you intend to map.

Example mapping table (maintain this in your ServiceNow script or a related list):

Finding ServiceNow service sys_id values

Your script should collect all relevant sys_id values (primary business service plus impacted services), deduplicate them, map each to a StatusDashboard component UUID, and send the resulting UUID array as componentIds (1–20 IDs per request).

If no mapped component is found, skip the webhook or log an error. StatusDashboard rejects triggers with unknown component IDs.

Step 3 — Define mapping dictionaries in ServiceNow

Add JavaScript objects at the top of your Business Rule (or in a Script Include) for the mappings below. Keys must match display values ServiceNow returns from getDisplayValue() unless you standardize on internal values.

State → workflow phase (statusLabel)

Map ServiceNow State to the exact incident workflow phase label configured in StatusDashboard (case-sensitive).

Default StatusDashboard incident phases:

Customize the dictionary to match your ServiceNow state list and your organization's workflow labels on Workflows.

Impact → severity (severity)

Map ServiceNow Impact display values to StatusDashboard severity labels (also case-sensitive).

Default StatusDashboard severities:

If you renamed severities in Settings, update the dictionary to match. You may omit severity on updates; severity is required on trigger only.

Description assembly

Decide how to build the StatusDashboard description from ServiceNow fields:

Use Short description for the webhook title on trigger (max 250 characters).

Step 4 — Track the StatusDashboard event ID

Your Business Rule tracks which StatusDashboard event corresponds to each ServiceNow incident. Store the StatusDashboard event UUID on the incident record and reference it on every update.

Recommended pattern:

1. Add a custom string field on Incident (for example u_statusdashboard_event_id) to store the StatusDashboard event UUID.
2. On insert, send action: "trigger" with idempotencyKey set to the incident sys_id (letters, numbers, dots, underscores, and hyphens only; max 128 characters).
3. After the first successful trigger, obtain the assigned event ID and write it to your custom field. Practical options:
   • Webhook logs API: Call GET /app/integrations/webhooks/inbound/logs (see List inbound webhook logs) and match the newest processed entry whose payload contains your idempotencyKey. Use the returned eventId.
   • Manual (pilot): Copy the Event ID from the matching row on Inbound webhooks webhook logs during testing.
4. On update, read u_statusdashboard_event_id. If populated, send action: "update". If empty, treat the next operation as a trigger (with the same idempotencyKey) or resolve the ID from logs before updating.

Optionally set a private webhook attribute on trigger so support staff can correlate records:

"attributes": [
  { "key": "servicenow_incident_id", "value": "<incident_sys_id>", "isPublic": false }
]

Step 5 — Create the Business Rule

Create a Business Rule in ServiceNow with these settings:

Script structure (outline)

Implement the Advanced script using standard ServiceNow APIs. A typical flow:

1. Load configuration — endpoint URL, Key ID, Signing Secret, mapping dictionaries, notification flags.
2. Build componentIds — query Business service, Impacted Services/CIs (task_cmdb_ci_service), map each sys_id through your component dictionary; exit if the array is empty.
3. Choose action:
   • insert → trigger
   • update with stored eventId → update
   • update without stored eventId → trigger with idempotencyKey (or resolve ID first)
4. Build JSON payload — see Payload reference below.
5. Sign the body — compute HMAC-SHA256 over "<unix_seconds>.<raw_json_body>" with the Signing Secret; set headers Content-Type, X-SD-Key-Id, and X-SD-Signature: t=<seconds>,v1=<hex>.
6. Send — RESTMessageV2 POST to https://api.statusdashboard.com/public/webhooks/inbound.
7. Persist eventId — on first successful processing, update u_statusdashboard_event_id (via logs API poll or your chosen method).
8. Log — use gs.info / gs.error behind a debug flag for troubleshooting.

Consider moving signing and HTTP into a Script Include (for example StatusDashboardWebhookClient) so the Business Rule stays readable and you can unit-test mappings separately.

Payload reference

All requests POST JSON to the inbound webhook endpoint. See Payload reference for full field definitions.

Trigger — new incident (action: "trigger")

Send on ServiceNow insert, or on update when no StatusDashboard eventId is stored yet.

{
  "action": "trigger",
  "title": "Elevated API error rate",
  "description": "Customers may see timeouts on login. Engineering is engaged.",
  "severity": "Major Outage",
  "componentIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "statusLabel": "Investigating",
  "initialMessage": "Incident opened from ServiceNow.",
  "idempotencyKey": "a1b2c3d4e5f6789012345678901234ab",
  "notifications": true,
  "attributes": [
    { "key": "servicenow_incident_id", "value": "a1b2c3d4e5f6789012345678901234ab", "isPublic": false }
  ]
}

Update — advance an existing incident (action: "update")

Send on ServiceNow update when u_statusdashboard_event_id is populated.

{
  "action": "update",
  "eventId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "statusLabel": "Identified",
  "message": "Root cause identified. Fix rolling out to all regions.",
  "notifications": true
}

Customer-visible comments

ServiceNow Customer visible comments map to StatusDashboard timeline entries.

When current.comments.changes() on an update:

1. Read the latest customer-visible journal entry (comments.getJournalEntry(1)).
2. Strip the journal header (text before the first newline) and trailing blank lines.
3. Send action: "update" with message set to the cleaned comment text and statusLabel set to the phase mapped from the incident's current State.

If the user edits State, Impact, or descriptions and posts a customer-visible comment in one save, prefer one webhook that includes the comment as the timeline message and the updated statusLabel. Avoid posting the comment first and saving field changes separately, which can produce two StatusDashboard timeline entries and duplicate notifications.

Notification suppression

To suppress subscriber notifications for a specific webhook while still creating or updating the incident:

Inbound webhook notification defaults and segment targeting are documented on Inbound webhooks.

What triggers the Business Rule

Actions in ServiceNow that should send a webhook:

Skip or filter incidents that should never appear on public status dashboards (internal-only categories, test assignment groups, and so on) using Business Rule conditions.

Testing and troubleshooting

1. Enable debug logging in your script and watch System Logs in ServiceNow.
2. Send a test incident with one mapped component and a known State / Impact.
3. Open Inbound webhooks and review Webhook logs:
   • processed — incident created or updated; note the Event ID
   • processing_failed — check Reason (invalid severity label, unknown component ID, invalid workflow phase, plan limits)
   • validation_failed — malformed JSON or missing required fields
4. Remember that authentication failures return 200 { "ok": true } by design. If nothing appears in logs, verify Key ID, Signing Secret, and the signature timestamp (must be within 5 minutes).