Webhook Endpoints

Webhooks allow you to receive real-time HTTP callbacks when events occur in VeraID. Each webhook is configured with a target URL and a list of event types to subscribe to. All webhook payloads are signed with HMAC-SHA256 for verification.

List Webhooks

Retrieve all configured webhooks for your organization.

GET /api/v1/webhooks

Example Request

curl -X GET https://app.veraid.io/api/v1/webhooks \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "wh_abc123",
      "name": "Production Event Handler",
      "url": "https://api.company.com/webhooks/veraid",
      "events": [
        "identity.created",
        "identity.suspended",
        "credential.rotated",
        "anomaly.detected"
      ],
      "status": "ACTIVE",
      "signingSecret": "whsec_••••••••",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-03-01T14:30:00Z",
      "stats": {
        "totalDeliveries": 4521,
        "successfulDeliveries": 4498,
        "failedDeliveries": 23,
        "lastDeliveryAt": "2026-03-19T09:30:00Z",
        "lastDeliveryStatus": "SUCCESS"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  }
}

---

Create Webhook

Register a new webhook endpoint.

POST /api/v1/webhooks

Request Body

Field	Type	Required	Description
name	string	Yes	Display name (2-100 characters)
url	string	Yes	Target URL (must be a valid URI with HTTPS scheme)
events	string[]	Yes	List of event types to subscribe to

Example Request

curl -X POST https://app.veraid.io/api/v1/webhooks \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Event Handler",
    "url": "https://api.company.com/webhooks/veraid-security",
    "events": [
      "identity.created",
      "identity.updated",
      "identity.suspended",
      "identity.revoked",
      "credential.created",
      "credential.used",
      "credential.expired",
      "credential.revoked",
      "policy.violated",
      "anomaly.detected",
      "alert.triggered"
    ]
  }'

Example Response

{
  "id": "wh_def456",
  "name": "Security Event Handler",
  "url": "https://api.company.com/webhooks/veraid-security",
  "events": [
    "identity.created",
    "identity.updated",
    "identity.suspended",
    "identity.revoked",
    "credential.created",
    "credential.used",
    "credential.expired",
    "credential.revoked",
    "policy.violated",
    "anomaly.detected",
    "alert.triggered"
  ],
  "status": "ACTIVE",
  "signingSecret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

Danger

The signingSecret is only returned in full when the webhook is created. Store it securely. You will need it to verify incoming webhook signatures.

---

Get Webhook

Retrieve a single webhook by ID.

GET /api/v1/webhooks/{id}

Example Request

curl -X GET https://app.veraid.io/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "id": "wh_abc123",
  "name": "Production Event Handler",
  "url": "https://api.company.com/webhooks/veraid",
  "events": [
    "identity.created",
    "identity.suspended",
    "credential.rotated",
    "anomaly.detected"
  ],
  "status": "ACTIVE",
  "signingSecret": "whsec_••••••••",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-01T14:30:00Z",
  "stats": {
    "totalDeliveries": 4521,
    "successfulDeliveries": 4498,
    "failedDeliveries": 23,
    "lastDeliveryAt": "2026-03-19T09:30:00Z",
    "lastDeliveryStatus": "SUCCESS"
  }
}

---

Update Webhook

Update an existing webhook’s name, URL, or event subscriptions.

PUT /api/v1/webhooks/{id}

Example Request

curl -X PUT https://app.veraid.io/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Event Handler (Updated)",
    "events": [
      "identity.created",
      "identity.suspended",
      "identity.revoked",
      "credential.rotated",
      "credential.revoked",
      "anomaly.detected",
      "alert.triggered"
    ]
  }'

Example Response

{
  "id": "wh_abc123",
  "name": "Production Event Handler (Updated)",
  "url": "https://api.company.com/webhooks/veraid",
  "events": [
    "identity.created",
    "identity.suspended",
    "identity.revoked",
    "credential.rotated",
    "credential.revoked",
    "anomaly.detected",
    "alert.triggered"
  ],
  "status": "ACTIVE",
  "signingSecret": "whsec_••••••••",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-19T10:05:00Z"
}

---

Delete Webhook

Delete a webhook. No further events will be delivered to the endpoint.

DELETE /api/v1/webhooks/{id}

Example Request

curl -X DELETE https://app.veraid.io/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "message": "Webhook deleted successfully",
  "id": "wh_abc123"
}

---

Test Webhook

Send a test event to the webhook endpoint to verify connectivity and signature verification.

POST /api/v1/webhooks/{id}/test

Example Request

curl -X POST https://app.veraid.io/api/v1/webhooks/wh_abc123/test \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "status": "SUCCESS",
  "message": "Test event delivered successfully",
  "details": {
    "responseCode": 200,
    "latency": "120ms",
    "responseBody": "{\"received\": true}"
  }
}

---

Event Types

Subscribe to any combination of the following event types:

Identity Events

Event	Description
identity.created	A new identity was created
identity.updated	An identity’s configuration was modified
identity.suspended	An identity was suspended
identity.revoked	An identity was permanently revoked or deleted

Credential Events

Event	Description
credential.created	A new credential was issued
credential.used	A credential was used to authenticate
credential.expired	A credential reached its expiration date
credential.revoked	A credential was manually revoked or rotated

Security Events

Event	Description
policy.violated	An identity attempted an action that violates a policy
anomaly.detected	Anomalous behavior was detected by the analysis engine
alert.triggered	A new security alert was generated

---

Webhook Payload Format

All webhook deliveries use the following envelope format:

{
  "id": "evt_abc123",
  "type": "credential.rotated",
  "timestamp": "2026-03-19T10:00:00Z",
  "webhookId": "wh_abc123",
  "data": {
    "credentialId": "cred_xyz789",
    "identityId": "id_def456",
    "identityName": "aws-deploy-prod",
    "rotatedBy": "SYSTEM",
    "reason": "Scheduled rotation (90-day policy)",
    "previousCredentialExpiry": "2026-03-20T10:00:00Z"
  }
}

---

Signature Verification

All webhook payloads are signed using HMAC-SHA256. Verify the signature to ensure the payload was sent by VeraID and has not been tampered with.

Headers

Header	Description
X-VeraID-Signature	HMAC-SHA256 signature of the raw request body
X-VeraID-Timestamp	Unix timestamp of when the webhook was sent

Verification Process

1. Concatenate the timestamp and raw request body: {timestamp}.{body}
2. Compute the HMAC-SHA256 using your webhook’s signing secret.
3. Compare the computed signature with the X-VeraID-Signature header.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Caution

Always use a constant-time comparison function (like crypto.timingSafeEqual) when verifying signatures to prevent timing attacks. Also validate that the timestamp is within 5 minutes of the current time to prevent replay attacks.

---

Retry Policy

Failed webhook deliveries are retried automatically with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

A delivery is considered failed if:

• The endpoint returns a non-2xx HTTP status code.
• The endpoint does not respond within 30 seconds.
• A network error occurs (DNS resolution failure, connection refused, etc.).

Dead-Letter Queue

After all retry attempts are exhausted, the failed event is moved to a dead-letter queue (DLQ). You can review and replay DLQ events from the VeraID dashboard under Settings > Webhooks > Dead Letter Queue.

DLQ events are retained for 30 days. Each entry includes the original payload, delivery attempts with timestamps and error details, and a one-click replay option.

Note

If a webhook endpoint fails consistently (more than 50 consecutive failures), VeraID automatically disables the webhook and sends a notification to organization administrators. Re-enable the webhook after resolving the endpoint issue.