Webhook Endpoints

Webhooks require the Pro plan or higher. Endpoint limits by tier: Pro 3, Business 10, Enterprise unlimited. The Free plan cannot create 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/webhooks`	Any member	`webhooks:read`
`POST /api/v1/org/webhooks`	Admin	`webhooks:write`
`PATCH /api/v1/org/webhooks/:id`	Admin	`webhooks:write`
`DELETE /api/v1/org/webhooks/:id`	Admin	`webhooks:delete`
`POST /api/v1/org/webhooks/:id/test`	Admin	`webhooks:test`
`GET /api/v1/org/webhooks/:id/deliveries`	Any member	`webhooks:read`
`POST /api/v1/org/webhooks/:id/deliveries/:deliveryId/retry`	Admin	`webhooks:write`

List webhook endpoints

GET /api/v1/org/webhooks

Returns all configured webhook endpoints for the organization, newest first. Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/hooks/grantiva",
    "events": ["device.new", "device.high_risk"],
    "isActive": true,
    "description": "Production event receiver",
    "createdAt": "2026-03-01T12:00:00Z",
    "updatedAt": "2026-03-10T08:30:00Z"
  }
]

The signing secret is not included — it is returned only at creation time.

Create a webhook endpoint

POST /api/v1/org/webhooks

Request body

{
  "url": "https://example.com/hooks/grantiva",
  "events": ["device.new", "device.high_risk"],
  "description": "Production event receiver"
}

Field	Type	Required	Description
`url`	string	Yes	Destination URL
`events`	string[]	Yes	Event types to subscribe to. Must contain at least one
`description`	string	No	Human-readable label for this endpoint

Supported event types device.new, device.attested.first, device.high_risk, device.attestation_failed, attestation.anomaly, flag.created, flag.updated, flag.deleted, subscription.changed, subscription.expired, subscription.refunded. Payloads for each are in Webhook Events. Response — 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/hooks/grantiva",
  "events": ["device.new"],
  "isActive": true,
  "description": "Production event receiver",
  "secret": "whsec_abc123...",
  "createdAt": "2026-03-01T12:00:00Z"
}

The secret field is returned only at creation time. Store it immediately — it cannot be retrieved again. Use it to verify the X-Grantiva-Signature header on incoming deliveries.

Errors

Status	Meaning
400	`url` is not a valid URL, or `events` is empty
403	Free plan, or the endpoint limit for your tier is reached

Update a webhook endpoint

PATCH /api/v1/org/webhooks/:id

Toggle the endpoint on or off, change subscribed events, or update the description. All fields are optional. Request body

{
  "isActive": false,
  "events": ["device.new", "attestation.anomaly"],
  "description": "Updated label"
}

Response — 200 OK — the updated endpoint object (same shape as the list response, without secret).

Delete a webhook endpoint

DELETE /api/v1/org/webhooks/:id

Permanently removes the webhook endpoint. In-flight deliveries are not retried after deletion. Response — 204 No Content

Send a test delivery

POST /api/v1/org/webhooks/:id/test

Synchronously delivers a synthetic attestation.completed event to the endpoint’s configured URL and returns the outcome. The test delivery:

is signed with the endpoint’s secret (X-Grantiva-Signature), exactly like a real delivery
does not create a delivery record and is not retried on failure
includes "is_test": "true" in the payload data
is sent regardless of which events the endpoint subscribes to

Test payload sent to your endpoint

{
  "event": "attestation.completed",
  "timestamp": "2026-07-26T12:00:00Z",
  "data": {
    "key_id": "test_key_550e8400",
    "device_id": "test_device_550e8400",
    "device_model": "iPhone16,2",
    "bundle_id": "com.example.app",
    "risk_score": "5",
    "attestation_id": "a3f1c9e2-...",
    "is_test": "true"
  }
}

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`	`attestation.completed`
`X-Grantiva-Delivery`	`test-<uuid>`
`User-Agent`	`Grantiva-Webhooks/1.0`

attestation.completed is a test-only event name. It is not a subscribable event type — real attestation events arrive as device.new, device.high_risk, and the others listed above.

Response — 200 OK

{
  "success": true,
  "httpStatus": 200,
  "responseBody": "ok",
  "latencyMs": 142,
  "error": null
}

Field	Type	Description
`success`	boolean	`true` when your endpoint returned a 2xx status
`httpStatus`	integer \| null	HTTP status your endpoint returned; `null` if the connection failed
`responseBody`	string \| null	First 200 characters of your endpoint’s response body
`latencyMs`	integer	Round-trip latency in milliseconds
`error`	string \| null	`"HTTP <status>"` for non-2xx responses, or the transport error message

List deliveries

GET /api/v1/org/webhooks/:id/deliveries

Paginated delivery history for a webhook endpoint, newest first. Query parameters

Parameter	Default	Description
`page`	1	Page number
`per`	20	Items per page (max 100)

Response

{
  "items": [
    {
      "id": "7f3e2a10-1b2c-4d5e-8f90-112233445566",
      "webhookId": "550e8400-e29b-41d4-a716-446655440000",
      "eventType": "device.new",
      "status": "success",
      "httpStatus": 200,
      "responseBody": "ok",
      "error": null,
      "attemptCount": 1,
      "nextRetryAt": null,
      "deliveredAt": "2026-07-26T12:00:03Z",
      "createdAt": "2026-07-26T12:00:02Z"
    }
  ],
  "metadata": {
    "page": 1,
    "per": 20,
    "total": 42
  }
}

Field	Type	Description
`status`	string	`pending`, `success`, or `failed`
`httpStatus`	integer \| null	Last HTTP status returned by your endpoint
`responseBody`	string \| null	First 1000 characters of your response from the last attempt
`error`	string \| null	Last error message, if any
`attemptCount`	integer	Delivery attempts so far — up to 3, with 1 min / 5 min / 30 min backoff
`nextRetryAt`	string \| null	When the next automatic retry is scheduled
`deliveredAt`	string \| null	When the delivery succeeded

Errors

Status	Meaning
403	Organization is on the Free plan
404	Webhook not found in this organization

Retry a delivery

POST /api/v1/org/webhooks/:id/deliveries/:deliveryId/retry

Manually re-sends a delivery with the original payload. The delivery is reset to pending with attemptCount back to 0, giving it a fresh automatic-retry budget, and the HTTP call fires in the background — the response reflects the reset state, not the outcome of the new attempt. Poll the deliveries list to see the result. Response — 200 OK Returns the delivery object (same shape as the list items) with status: "pending" and attemptCount: 0. Errors

Status	Meaning
403	Organization is on the Free plan
404	Webhook or delivery not found in this organization
422	The webhook endpoint is inactive — re-enable it before retrying

Signature verification

Every delivery includes an X-Grantiva-Signature header: the string sha256= followed by the hex-encoded HMAC-SHA256 of the raw request body, keyed with your endpoint’s secret. Verify the signature before processing any payload:

import CryptoKit

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

For Node.js, Python, and Go examples see Webhooks Concepts.

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Webhook Endpoints

Authentication

List webhook endpoints

Create a webhook endpoint

Update a webhook endpoint

Delete a webhook endpoint

Send a test delivery

List deliveries

Retry a delivery

Signature verification

See also

​Authentication

​List webhook endpoints

​Create a webhook endpoint

​Update a webhook endpoint

​Delete a webhook endpoint

​Send a test delivery

​List deliveries

​Retry a delivery

​Signature verification

​See also

Authentication

List webhook endpoints

Create a webhook endpoint

Update a webhook endpoint

Delete a webhook endpoint

Send a test delivery

List deliveries

Retry a delivery

Signature verification

See also