Risk Alert Rules

Configuring risk alert rules and reading the delivery log require the Business plan or higher. Listing existing rules is available to 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 an X-Grantiva-Signature header — an HMAC-SHA256 of the raw body, signed with the rule’s secret (generated at rule creation).

Authentication

All endpoints require a dashboard session (cookie-based) with organization context. Creating, updating, and deleting rules additionally requires Admin role or above.

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
`X-Grantiva-Signature`	HMAC-SHA256 signature of the raw body
`X-Grantiva-Event`	`risk_alert`
`X-Grantiva-Delivery`	Delivery UUID
`User-Agent`	`Grantiva-Webhooks/1.0`

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

Requires Admin role and Business plan or higher. 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.

Update a rule

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

Requires Admin role and Business plan or higher. 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

Requires Admin role and Business plan or higher. Response — 204 No Content

List alert deliveries

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

Requires Business plan or higher (any member role). 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