Risk Alert Rules

Creating, updating, and deleting rules and reading the delivery log require the Business plan or higher. Listing existing rules is available on all plans.

Risk alert rules are evaluated after every attestation, once the device’s risk score is computed. When a score crosses a rule’s threshold, Grantiva POSTs an alert payload to the rule’s webhook URL. Alerts never block or slow down the attestation path — delivery happens in the background. Delivery behavior

Cooldown: the same device will not re-trigger the same rule within 1 hour.
Retries: up to 3 attempts per alert, with 1 min / 5 min / 30 min backoff.
Signing: every request carries X-Grantiva-Signature — sha256= followed by the hex HMAC-SHA256 of the raw body, computed with a signing secret generated for the rule. The scheme matches webhook endpoints.

Authentication

These endpoints accept either a dashboard session cookie or a server API key sent as Authorization: Bearer <key>.

Endpoint	Session role	Key scope
`GET /api/v1/org/risk-alerts/rules`	Any member	`alerts:read`
`POST /api/v1/org/risk-alerts/rules`	Admin	`alerts:write`
`PATCH /api/v1/org/risk-alerts/rules/:ruleId`	Admin	`alerts:write`
`DELETE /api/v1/org/risk-alerts/rules/:ruleId`	Admin	`alerts:write`
`GET /api/v1/org/risk-alerts/deliveries`	Any member	`alerts:read`

Alert payload

When a rule fires, your webhook URL receives:

{
  "bundleId": "com.yourapp.example",
  "crossedAt": "2026-07-26T12:00:00Z",
  "deviceId": "abc123keyid",
  "riskScore": 87,
  "teamId": "ABBM6U9RM5",
  "threshold": 75
}

Headers on the outgoing request:

Header	Value
`Content-Type`	`application/json`
`X-Grantiva-Signature`	`sha256=<hex HMAC-SHA256 of the raw body>`
`X-Grantiva-Event`	`risk_alert`
`X-Grantiva-Delivery`	Delivery UUID
`User-Agent`	`Grantiva-Webhooks/1.0`

On an automatic retry, bundleId and teamId are sent as empty strings — the retry rebuilds the payload from the stored delivery record, which keeps only the device and score. Key your handling on deviceId.

List rules

GET /api/v1/org/risk-alerts/rules

Returns all alert rules for the organization, newest first. Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Critical risk devices",
    "threshold": 75,
    "comparison": "gt",
    "webhookUrl": "https://example.com/hooks/risk-alerts",
    "isActive": true,
    "createdAt": "2026-06-01T12:00:00Z"
  }
]

Create a rule

POST /api/v1/org/risk-alerts/rules

Request body

{
  "name": "Critical risk devices",
  "threshold": 75,
  "comparison": "gt",
  "webhookUrl": "https://example.com/hooks/risk-alerts"
}

Field	Type	Required	Description
`name`	string	Yes	Label, 1–100 characters
`threshold`	integer	Yes	Risk score threshold, 0–100
`comparison`	string	Yes	`gt` (score > threshold) or `gte` (score >= threshold)
`webhookUrl`	string	Yes	URL to POST alert payloads to

Response — 201 Created Returns the rule object (same shape as the list response). New rules are active immediately. Errors

Status	Meaning
403	Not an Admin, or plan below Business
400	Validation failed — `name` empty or over 100 characters, `threshold` outside 0–100, `comparison` not `gt`/`gte`, or `webhookUrl` empty

Update a rule

PATCH /api/v1/org/risk-alerts/rules/:ruleId

All fields are optional; only provided fields change. Request body

{
  "name": "High risk devices",
  "threshold": 60,
  "comparison": "gte",
  "webhookUrl": "https://example.com/hooks/risk-alerts-v2",
  "isActive": false
}

Response — 200 OK Returns the updated rule object. Errors

Status	Meaning
400	`threshold` outside 0–100, or `comparison` not `gt`/`gte`
403	Not an Admin, or plan below Business
404	Rule not found in this organization

Delete a rule

DELETE /api/v1/org/risk-alerts/rules/:ruleId

Response — 204 No Content

List alert deliveries

GET /api/v1/org/risk-alerts/deliveries

Returns the 200 most recent alert deliveries across all of the organization’s rules, newest first. Response

[
  {
    "id": "7f3e2a10-1b2c-4d5e-8f90-112233445566",
    "ruleId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceId": "abc123keyid",
    "riskScore": 87,
    "status": "success",
    "attemptCount": 1,
    "httpStatus": 200,
    "error": null,
    "deliveredAt": "2026-07-26T12:00:03Z",
    "createdAt": "2026-07-26T12:00:02Z"
  }
]

Field	Type	Description
`status`	string	`pending`, `success`, or `failed` (failed after 3 attempts)
`attemptCount`	integer	Delivery attempts made
`httpStatus`	integer \| null	Last HTTP status your endpoint returned
`error`	string \| null	Last error, e.g. `"HTTP 500"` or a transport error
`deliveredAt`	string \| null	When delivery succeeded

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Authentication

Alert payload

List rules

Create a rule

Update a rule

Delete a rule

List alert deliveries

See also

​Authentication

​Alert payload

​List rules

​Create a rule

​Update a rule

​Delete a rule

​List alert deliveries

​See also

Authentication

Alert payload

List rules

Create a rule

Update a rule

Delete a rule

List alert deliveries

See also