Custom Webhooks Quick Reference

Webhook URL Format

https://your-tobealert.com:9000/api/webhooks/custom/{webhook-id}

Inbound method: POST only. No inbound authentication in this version.

Creating a Webhook

curl -X POST http://your-tobealert.com:9000/api/webhook_config \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
    "id": "my-webhook",
    "name": "My Monitoring Integration",
    "fieldMappings": {
      "resource": "hostname",
      "event": "check",
      "severity": "severity",
      "text": "message"
    },
    "defaultValues": {
      "environment": "Production",
      "type": "webhook",
      "origin": "my-monitoring"
    }
  }'

Field mapping syntax

Mappings copy values as they are — no ${…} templates, expressions, or functions. Full details: Field Mapping Reference.

Mapping value	Result
"field"	Value of a top-level key
"object.property"	Nested value (dot notation)
"array[0]", "array[0].name"	Array element by index
"array" / "array[]"	Whole array, as a list
{"path": "array", "join": ", "}	Array joined into one string
{"path": "array[]", "expand": true}	One alert per element; "other[N]" reads the same index
{"path": "flag", "if_true": "critical", "if_false": "warning"}	Fixed value chosen by a boolean
"attributes": {"key": "path", …}	Custom attributes, same syntax
123, true	Literal number / boolean

A string is always a path. Fixed text ("environment": "Production", "origin": "nagios") goes in defaultValues; a default also fills a field whose path is missing from the payload. arrayPath (for example alerts) makes one alert per element and reads every mapping inside it.

Required: resource, event, environment, type, text, severity. severity must be a ToBeAlert severity (critical, major, minor, warning, …); service and tags must be lists.

Common Mappings

Severity from a boolean

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

Severity from another vocabulary (CRITICAL, ALARM, high)

"fieldMappings": { "attributes": { "source_status": "status" } },
"defaultValues": { "severity": "warning" }

Then a policy: attributes key source_status Equals CRITICAL → severity set critical. See Transforming values.

Links in Attributes

"attributes": {
  "dashboard": "links.dashboard",
  "runbook": "annotations.runbook"
}

The payload must carry the complete URL; mappings cannot build one from parts.

Tags

"tags": "labels_list"

Map an array from the payload, or set a fixed list in defaultValues ("tags": ["webhook"]).

Case, trim, thresholds

Not done by the mapping. Use a policy with a custom tool.

Managing Webhooks

Action	Command
List all	GET /api/webhook_configs
Get one	GET /api/webhook_config/{id}
Update	PUT /api/webhook_config/{id}
Delete	DELETE /api/webhook_config/{id}

Testing

# Test webhook
curl -X POST https://your-tobealert.com:9000/api/webhooks/custom/my-webhook \
  -H "Content-Type: application/json" \
  -d '{"hostname": "web-01", "check": "cpu", "severity": "warning", "message": "High CPU"}'

Response: {"status": "ok", "webhook_id": "my-webhook", "webhook_name": "…", "alerts_created": 1, "alerts": [{"id": "…", "resource": "web-01", "event": "cpu", "severity": "warning"}]}. Failed alerts are listed in errors (alert_data, error); status is then partial (200) or error (400).