Webhooks

Webhooks send HTTP POST requests to your server when events occur in Grantiva. Available on Pro, Business, and Enterprise plans.

Events

Event	Description
`device.new`	First attestation from a new device
`device.attested.first`	A device completes its first successful attestation
`device.high_risk`	Device risk score exceeds your threshold
`device.attestation_failed`	A device fails attestation validation
`attestation.anomaly`	Unusual attestation pattern detected
`flag.created`	A feature flag was created
`flag.updated`	A feature flag’s value or state changed
`flag.deleted`	A feature flag was deleted
`subscription.changed`	A subscription entitlement changed (Enterprise — see Subscription Claims)
`subscription.expired`	An entitlement expired or was revoked
`subscription.refunded`	An entitlement was refunded

Setup

Create webhook endpoints from the dashboard under Settings > Webhooks.

Enter your endpoint URL (must be HTTPS)
Select which events to subscribe to
Save — Grantiva generates a signing secret (whsec_...)

Payload format

{
  "event": "device.high_risk",
  "timestamp": "2025-03-10T12:00:00Z",
  "data": {
    "device_id": "abc123",
    "risk_score": 82,
    "jailbreak_detected": true,
    "device_model": "iPhone15,2",
    "os_version": "18.0"
  }
}

Verifying signatures

Every webhook request includes an X-Grantiva-Signature header containing an HMAC-SHA256 signature of the request body, signed with your endpoint’s secret.

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

import Crypto

func verifyWebhook(body: Data, signature: String, secret: String) -> Bool {
    let key = SymmetricKey(data: Data(secret.utf8))
    let mac = HMAC<SHA256>.authenticationCode(for: body, using: key)
    let expected = "sha256=" + mac.map { String(format: "%02x", $0) }.joined()
    return expected == signature
}

Always verify signatures before processing webhook payloads.

Subscription events

subscription.changed fires whenever a subscription entitlement materially changes (tier, status, interval, expiry, auto-renew, or product); identical redeliveries from Apple/Stripe do not re-fire it. subscription.expired additionally fires when status becomes expired or revoked, and subscription.refunded on refunds.

{
  "event": "subscription.changed",
  "timestamp": "2026-06-22T19:00:00Z",
  "data": {
    "subject_id": "<sharing-unit UUID>",
    "tier": "plus",
    "status": "active",
    "interval": "annual",
    "source": "apple",
    "product_id": "com.example.plus.annual",
    "expires_at": "2026-12-01T00:00:00Z",
    "source_subscription_id": "2000000xxxxxxxxx",
    "environment": "production",
    "auto_renew": "true",
    "event_id": "<uuid>"
  }
}

Handling notes:

Dedupe on data.event_id and key any cache eviction by data.subject_id.
expires_at is ISO-8601 here but epoch seconds in the JWT claim — each surface follows its own convention.
Treat the webhook as a cache-bust nudge: re-read the claim from the next JWT rather than trusting the webhook body as authoritative.

Retries

Failed deliveries (non-2xx response or timeout) are retried up to 3 times with exponential backoff. You can view delivery history and response details in the dashboard.

Testing

Send a test event from the webhook detail page in the dashboard (or POST /api/v1/org/webhooks/:id/test). This synchronously delivers a synthetic attestation.completed payload — signed like a real event — and reports the HTTP status your endpoint returned, so you can verify reachability and signature handling.

Getting Started

iOS SDK

CLI

Concepts

Push

Dashboard

Events

Setup

Payload format

Verifying signatures

Subscription events

Retries

Testing

​Events

​Setup

​Payload format

​Verifying signatures

​Subscription events

​Retries

​Testing

Events

Setup

Payload format

Verifying signatures

Subscription events

Retries

Testing