Field Mapping Reference

A webhook configuration turns each inbound JSON payload into one or more alerts with three settings:

Setting	API field	What it does
Array Path	arrayPath	Optional path to an array in the payload. Each item becomes one alert. Empty: the whole payload is one alert
Field mappings	fieldMappings	Object whose keys are alert fields and whose values say where to read each value in the payload
Default values	defaultValues	Fixed values used when a field is not mapped or its path is missing from the payload

Mappings copy values as they are. There are no templates, expressions, or functions: a mapping never combines several fields, changes case, or computes a number. To reshape values after they arrive, use a policy — see Transforming values.

Paths

A mapping value that is a string is always read as a path into the payload (or into the current array item when Array Path is set).

Path	Reads	Payload	Result
hostname	A top-level key	{"hostname": "web-01"}	"web-01"
server.name	A nested key (dot notation)	{"server": {"name": "db-01"}}	"db-01"
checks[0]	One array element (index from 0)	{"checks": ["disk", "cpu"]}	"disk"
events[1].type	A key inside an array element	{"events": [{"type": "a"}, {"type": "b"}]}	"b"
tags or tags[]	The whole array	{"tags": ["prod", "linux"]}	["prod", "linux"]

The value is copied with its JSON type: a number stays a number, an array stays an array, an object stays an object.

When a path does not exist (unknown key, index out of range, a key read on something that is not an object), the field is left out of the alert, and the default value for that field is used if there is one. No error is raised for a missing path.

Fixed text goes in defaultValues

Because every string is a path, "origin": "prometheus" in fieldMappings does not set the text prometheus: it looks for a key called prometheus in the payload and, not finding it, leaves origin out. Put fixed text in defaultValues instead. Template strings such as "${hostname}" or "${hostname}-${check}" are read the same way, as a path that does not exist, so the field is silently dropped.

Only numbers, booleans, and null are copied literally from fieldMappings (for example "timeout": 3600).

Arrays

Join into one string

{"path": "...", "join": "<separator>"} turns an array into one string. Each element is converted to text.

{
  "fieldMappings": {
    "text": { "path": "errors", "join": ", " }
  }
}

Payload {"errors": ["disk full", "inode limit"]} → text = "disk full, inode limit".

Without join, an array is copied as an array. That is what service and tags need (both must be lists); for a text field such as text or resource, add join.

One alert per array element (expand)

{"path": "<array>[]", "expand": true} creates one alert per element of that array. In each alert the field receives a single element. Only one field per configuration can expand (the first one found).

In the other mappings of the same configuration, [N] stands for the index of the element being expanded, so you can read a parallel array:

{
  "fieldMappings": {
    "resource": { "path": "hosts[]", "expand": true },
    "text": "messages[N]",
    "event": "check"
  },
  "defaultValues": { "environment": "Production" }
}

Payload:

{ "check": "ping", "hosts": ["web-01", "web-02"], "messages": ["timeout", "packet loss"] }

Result — two alerts:

[
  { "resource": "web-01", "event": "ping", "text": "timeout", "environment": "Production" },
  { "resource": "web-02", "event": "ping", "text": "packet loss", "environment": "Production" }
]

[N] only works in plain string mappings and only when a field expands. If the array to expand is empty or missing, the item is mapped once, without expansion.

expand also works together with Array Path: every array item is expanded on its own.

Boolean conditions (if_true / if_false)

{"path": "...", "if_true": <value>, "if_false": <value>} writes one of two fixed values depending on the value at path:

{
  "fieldMappings": {
    "severity": { "path": "is_critical", "if_true": "critical", "if_false": "warning" }
  }
}

Payload	severity
{"is_critical": true}	critical
{"is_critical": false}	warning
no is_critical key	not mapped (default value if any)

Both if_true and if_false must be set. Values that are not booleans are judged by JSON truthiness: 0, "", [] and {} count as false, any other number or text (including the string "false") counts as true. There is no comparison with other values (== 'CRITICAL', > 90); for that, see Transforming values.

Custom attributes

attributes takes an object of mappings with the same syntax. Each key becomes a custom attribute:

{
  "fieldMappings": {
    "attributes": {
      "cpu": "metrics.cpu",
      "runbook": "links.runbook",
      "region": "location.region"
    }
  },
  "defaultValues": {
    "attributes": { "team": "platform" }
  }
}

Payload {"metrics": {"cpu": 95.2}, "links": {"runbook": "https://wiki.example.com/cpu"}} → attributes = {"cpu": 95.2, "runbook": "https://wiki.example.com/cpu", "team": "platform"}. region is left out because location.region is missing.

Defaults for attributes go inside defaultValues.attributes and are merged key by key. attributes is the only nested mapping object that ends up in the alert. Another nested object (one without path) is rejected on save while the webhook is enabled, and ignored when the alert is created.

A link in an attribute must arrive complete in the payload (or be a fixed default). Mappings cannot build a URL from parts.

Default values

defaultValues is an object of fixed values with alert field names as keys:

{
  "defaultValues": {
    "environment": "Production",
    "type": "webhook",
    "origin": "nagios",
    "service": ["monitoring"],
    "group": "infrastructure"
  }
}

A default is used when the field is not in fieldMappings, or when it is mapped but the path is missing in this payload. A mapped value always wins over the default, even if the mapped value is an empty string.

Array Path

arrayPath is a path to an array (same syntax as above). Each element becomes one alert, and every mapping is read relative to that element:

{
  "arrayPath": "alerts",
  "fieldMappings": {
    "resource": "labels.instance",
    "event": "labels.alertname"
  }
}

arrayPath value	Behaviour
Empty / not set	The whole payload is one alert
Points to an array	One alert per element
Points to an object	That object is one alert
[]	The payload itself is a top-level array ([{...}, {...}])
Missing or empty array	No alert; the request returns 400 with No alerts generated from payload: array path "…" was not found or … is an empty list.

Mappings cannot read keys outside the current element. With Alertmanager, for example, commonLabels is not reachable once arrayPath is alerts; read the same labels from each alert instead.

Target alert fields

Keys of fieldMappings and defaultValues are alert fields as the alert API names them (camelCase).

Field	Type expected	Notes
resource, event, environment, type, text, severity	text	Required to enable the webhook: each needs a mapping or a non-empty default
severity	text	Must be one of the configured severities (critical, major, minor, warning, informational, normal, ok, …). Any other value fails the alert with Severity (…) is not one of …
service, tags, correlate	list	A single string fails the alert with service must be a list (or tags, …). Map an array, or set a list as default
attributes	object	See Custom attributes
group, value, origin, status	text	origin is optional
timeout	integer (seconds)
createTime	ISO 8601 date text	Parsed as a date
resourceParent	text	Parent in the resource graph
sourceId	text	Set automatically from the webhook's Alert source when there is one

Keys that are not alert fields are ignored when the alert is created. alert_id, for example, is not an alert field: ToBeAlert generates the alert id.

Validation on save

POST /api/webhook_config and PUT /api/webhook_config/{id} check:

• fieldMappings is an object; each value is a path string, a number, a boolean, null, an object with a string path, or a nested mapping object such as attributes.
• When the webhook is (or becomes) enabled, resource, event, environment, type, text, and severity are each in fieldMappings or have a non-empty default. A whitespace-only default does not count. A disabled webhook can be saved with incomplete or empty mappings.

The check only looks at keys: a mapped path that does not exist in real payloads passes validation, and the alert then fails at receive time (for example An environment must be provided). Test with a real payload before enabling the webhook.

Transforming values

Mappings copy values as they are. To change values, add a policy with trigger On alert creation and any change type: it runs on every alert that arrives through the webhook, before it is stored.

You want to	Use
Upper/lower case, capitalize, or trim text or an attribute	Modifier with a text transform (upper, lower, capitalize, trim)
Translate a source status (CRITICAL, ALARM, high) into a ToBeAlert severity	Map the status to an attribute, give severity a default, and add one policy per status: condition on the attribute, modifier severity set
Raise severity when a number crosses a threshold (97%, 1.5 GB)	Condition with Greater than on value or an attribute — see Numeric comparisons on text values — and modifier severity set or Severity step
Replace part of a text, or add a fixed tag or service	Modifier replace or add
Build values from several fields, parse dates, or call another system	A custom tool attached to the policy

Fields that policies treat as immutable (resource, event, environment, …) cannot be changed by a modifier: map them from a payload key that already has the right form, or keep the source value in an attribute and transform that. See Modifiers and tools.

Example — the sender reports "status": "CRITICAL", "WARNING" or "OK":

{
  "fieldMappings": {
    "resource": "host",
    "event": "check",
    "text": "message",
    "attributes": { "source_status": "status" }
  },
  "defaultValues": {
    "environment": "Production",
    "type": "nagios",
    "severity": "warning"
  }
}

Then a policy with condition attributes key source_status Equals CRITICAL and modifier severity set critical (and one for OK → normal).

Debugging mappings

• The Field Mapping Editor in the web UI previews the alerts your mapping produces from a sample payload. See Webhook Configurations.
• GET /api/webhook_config/{id} returns the last five received payloads (payloadHistory) and the last five failures with their message (errorHistory). Use a stored payload as the sample for the mapping. See Payload history, error history, and size limit.
• The inbound response lists each alert that failed with the mapped data and the reason (errors[].alert_data, errors[].error).