Webhook Formats

Overview

NearIRM accepts alerts via HTTP webhooks. Each integration type has its own endpoint and expected payload format.

See Authentication for security best practices around webhook URLs.

Grafana Alertmanager

Endpoint:

POST https://irm.nearlunar.com/api/webhooks/grafana/{integrationId}

Request Format

NearIRM accepts the standard Grafana Alertmanager webhook format:

{
  "receiver": "webhook",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "HighErrorRate",
        "severity": "critical",
        "service": "api",
        "env": "production"
      },
      "annotations": {
        "summary": "Error rate above threshold",
        "description": "API service error rate is 8.2%, threshold is 5%"
      },
      "startsAt": "2024-01-15T10:30:00Z",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://grafana.example.com/alerting/grafana/abc123"
    }
  ],
  "groupLabels": {
    "alertname": "HighErrorRate"
  },
  "commonLabels": {
    "alertname": "HighErrorRate",
    "severity": "critical"
  },
  "commonAnnotations": {
    "summary": "Error rate above threshold"
  },
  "externalURL": "https://grafana.example.com"
}

Required Fields

Field	Type	Description
`alerts`	array	List of alert objects
`alerts[].status`	string	`firing` or `resolved`
`alerts[].labels`	object	Key-value labels

Optional Fields

Field	Type	Description
`receiver`	string	Receiver name (informational)
`status`	string	Overall status
`alerts[].annotations`	object	Summary and description
`alerts[].startsAt`	string	ISO 8601 timestamp
`alerts[].endsAt`	string	ISO 8601 timestamp
`alerts[].generatorURL`	string	Link back to source
`groupLabels`	object	Labels used for grouping
`commonLabels`	object	Labels common to all alerts
`commonAnnotations`	object	Annotations common to all alerts
`externalURL`	string	Grafana instance URL

Severity Mapping

NearIRM maps the severity label to internal levels:

Grafana Label	NearIRM Level
`critical`	Critical
`warning`	High
`info`	Low
(not set)	Medium

SigNoz

Endpoint:

POST https://irm.nearlunar.com/api/webhooks/signoz/{integrationId}

Request Format

NearIRM accepts the standard Prometheus Alertmanager webhook format used by SigNoz:

{
  "receiver": "signoz-alert",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "HighMemoryUsage",
        "severity": "critical",
        "service": "payments",
        "env": "production"
      },
      "annotations": {
        "summary": "Memory usage above 90%",
        "description": "Payments service memory at 92%, threshold is 90%"
      },
      "startsAt": "2024-01-15T10:30:00Z",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://signoz.example.com/alerts/abc123",
      "fingerprint": "abc123def456"
    }
  ],
  "groupLabels": {
    "alertname": "HighMemoryUsage"
  },
  "commonLabels": {
    "alertname": "HighMemoryUsage",
    "severity": "critical"
  },
  "commonAnnotations": {
    "summary": "Memory usage above 90%"
  },
  "externalURL": "https://signoz.example.com",
  "version": "4",
  "groupKey": "{}:{alertname=\"HighMemoryUsage\"}"
}

Required Fields

Field	Type	Description
`receiver`	string	Receiver name
`status`	string	`firing` or `resolved`
`alerts`	array	List of alert objects (minimum 1)
`alerts[].status`	string	`firing` or `resolved`
`alerts[].labels`	object	Key-value labels (include `alertname` and `severity`)
`alerts[].startsAt`	string	ISO 8601 start timestamp
`alerts[].fingerprint`	string	Unique alert fingerprint

Optional Fields

Field	Type	Description
`alerts[].annotations`	object	Summary and description
`alerts[].endsAt`	string	ISO 8601 end timestamp
`alerts[].generatorURL`	string	Link back to SigNoz
`groupLabels`	object	Labels used for grouping
`commonLabels`	object	Labels common to all alerts
`commonAnnotations`	object	Annotations common to all alerts
`externalURL`	string	SigNoz instance URL
`version`	string	API version
`groupKey`	string	Group key for deduplication

Severity Mapping

NearIRM maps the severity label to internal levels:

SigNoz Label	NearIRM Level
`critical`	Critical
`error`	High
`warning`	Medium
`info`	Info
`p1`	Critical
`p2`	High
`p3`	Medium
`p4`	Low
`p5`	Info
(not set)	Medium

Authentication

SigNoz sends the API key as a Bearer token. NearIRM supports two authentication methods:

Primary: Authorization: Bearer <api_key> header (SigNoz default)
Fallback: X-API-Key: <api_key> header (backward compatibility)

Generic Webhook

Endpoint:

POST https://irm.nearlunar.com/api/webhooks/generic/{integrationId}

Request Format

{
  "title": "High CPU Usage",
  "description": "Server cpu-01 is at 95% CPU utilization",
  "severity": "critical",
  "status": "firing",
  "source": "custom-monitor",
  "incidentKey": "cpu-01-high-cpu",
  "labels": {
    "host": "cpu-01",
    "env": "production",
    "team": "infrastructure"
  }
}

Required Fields

Field	Type	Description
`title`	string	Alert title (displayed in list and notifications)

Optional Fields

Field	Type	Description	Default
`description`	string	Detailed information	(empty)
`severity`	string	`critical`, `high`, `medium`, `low`, `info`	`medium`
`status`	string	`firing` or `resolved`	`firing`
`source`	string	Source identifier	Integration name
`incidentKey`	string	Deduplication key	Generated from title + labels
`labels`	object	Key-value metadata	(empty)

Deduplication

Alerts are deduplicated by their incident key:

If incidentKey provided, that exact value is used
Otherwise, a fingerprint is generated from title + labels
Same incident key + same integration = same alert
Duplicate firing events update existing alert
resolved event closes the alert

Response Format

Success (202 Accepted)

{
  "success": true,
  "message": "Alert queued for processing"
}

The 202 status means the webhook was received and queued. Actual processing happens asynchronously.

Error Responses

See Error Codes for detailed error responses.

Example: curl

Grafana Format

curl -X POST \
  'https://irm.nearlunar.com/api/webhooks/grafana/abc123def456' \
  -H 'Content-Type: application/json' \
  -d '{
    "alerts": [{
      "status": "firing",
      "labels": {
        "alertname": "TestAlert",
        "severity": "warning"
      },
      "annotations": {
        "summary": "Test alert from curl"
      }
    }]
  }'

SigNoz Format

curl -X POST \
  'https://irm.nearlunar.com/api/webhooks/signoz/abc123def456' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "receiver": "test",
    "status": "firing",
    "alerts": [{
      "status": "firing",
      "labels": {
        "alertname": "TestAlert",
        "severity": "warning"
      },
      "annotations": {
        "summary": "Test alert from curl"
      },
      "startsAt": "2024-01-15T10:30:00Z",
      "fingerprint": "test-fingerprint-001"
    }]
  }'

Generic Format

curl -X POST \
  'https://irm.nearlunar.com/api/webhooks/generic/abc123def456' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Test Alert",
    "description": "Testing webhook integration",
    "severity": "warning",
    "labels": {
      "source": "curl-test"
    }
  }'

Rate Limits

Limit	Value
Requests per minute per integration	100
Payload size	1 MB
Alerts per request (Grafana)	100
Alerts per request (SigNoz)	100

Exceeding limits returns 429 Too Many Requests.

Webhook Formats

On this page