ServiceNow

Versus Incident can escalate unacknowledged alerts to ServiceNow by creating records through the ServiceNow Table API. When on-call is enabled with the servicenow provider, Versus posts a new record (by default to the incident table) for every incident that is not acknowledged within the configured wait period.

How it works

When an incident escalates, Versus sends an HTTP POST to:

{instance_url}/api/now/table/{table}

• Authentication uses HTTP Basic auth with the configured username and password.
• The incident ID is mapped onto two fields:
  • short_description — a human-readable summary (Incident <id>).
  • correlation_id — used by ServiceNow to de-duplicate inbound events.
• The request uses the shared HTTPS client with TLS verification enabled.

A non-2xx response from ServiceNow is treated as a failure and logged.

Configuration

Add the servicenow block under oncall in your config.yaml and set provider: servicenow:

oncall:
  enable: true
  wait_minutes: 3
  provider: servicenow

  servicenow:
    instance_url: ${SERVICENOW_INSTANCE_URL} # eg https://dev12345.service-now.com (REQUIRED)
    username: ${SERVICENOW_USERNAME}          # REQUIRED
    password: ${SERVICENOW_PASSWORD}          # REQUIRED
    table: incident                           # ServiceNow table; defaults to "incident"
    other_instance_urls:                      # Optional: per-request instance override
      infra: ${SERVICENOW_OTHER_INSTANCE_URL_INFRA}
      app: ${SERVICENOW_OTHER_INSTANCE_URL_APP}
      db: ${SERVICENOW_OTHER_INSTANCE_URL_DB}

redis: # Required for on-call functionality
  host: ${REDIS_HOST}
  port: ${REDIS_PORT}
  password: ${REDIS_PASSWORD}
  db: 0

Credentials

Provide username and password through environment variables (${SERVICENOW_USERNAME}, ${SERVICENOW_PASSWORD}) — never hard-code them in config.yaml. Versus never logs credentials.

Per-request override

You can route a specific alert to a different ServiceNow instance using the servicenow_other_instance query parameter. The value must match a key under other_instance_urls:

POST /api/incidents?servicenow_other_instance=infra

This overrides instance_url for that single request only; the global config is never mutated.

Environment variables