Webhook Management

Receive real-time notifications when events occur in your VeriSwarm workspace. Webhooks deliver HTTP POST requests to your endpoint whenever agents are scored, tiers change, security findings surface, or other significant events happen.

For payload signature verification, see the Webhook Security guide.

Creating a Webhook Endpoint

Via the Dashboard

Navigate to Account > Settings > Webhooks and click Create Webhook. Provide:

A label to identify the webhook (e.g., "Production Slack Notifier").
A callback URL -- the HTTPS endpoint that will receive POST requests. In production, HTTPS is required. The URL must not resolve to a private/internal IP address (SSRF protection).
One or more event types to subscribe to, or * for all events.

Via the API

curl -X POST https://veriswarm.ai/v1/public/providers/webhooks \
  -H "x-account-access-token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Score Change Alerts",
    "callback_url": "https://api.example.com/webhooks/veriswarm",
    "event_types": ["agent.scored", "agent.tier.changed", "agent.killed"]
  }'

Response (includes signing secret -- store it securely):

{
  "id": 42,
  "label": "Score Change Alerts",
  "callback_url": "https://api.example.com/webhooks/veriswarm",
  "event_types": ["agent.scored", "agent.tier.changed", "agent.killed"],
  "is_active": true,
  "created_at": "2026-03-28T12:00:00Z",
  "signing_secret": "whsec_abc123..."
}

The signing_secret is only returned at creation time. Store it immediately. See Webhook Security for how to use it.

Supported Event Types

Subscribe to specific events or use * to receive everything.

Core Events

Event Type	Description
`decision.checked`	A trust decision was evaluated for an agent
`provider.report.ingested`	A provider report was ingested into the system

Scoring Events

Event Type	Description
`agent.scored`	An agent's scores were recomputed
`agent.tier.changed`	An agent moved to a different policy tier
`agent.trust.drift`	Significant trust score change detected

Guard Events

Event Type	Description
`guard.finding.created`	A new security finding was detected
`guard.pii.detected`	PII was detected in agent communication
`guard.injection.detected`	A prompt injection attempt was detected
`guard.tool.blocked`	A tool call was blocked by policy

Kill Switch Events

Event Type	Description
`agent.killed`	An agent was emergency-stopped via kill switch
`agent.unkilled`	A killed agent was reactivated

Agent Lifecycle Events

Event Type	Description
`agent.registered`	A new agent was registered
`agent.deployed`	An agent was deployed
`agent.undeployed`	An agent was undeployed

Compliance Events

Event Type	Description
`compliance.control.failed`	A compliance control check failed
`vault.chain.broken`	The Vault hash chain integrity was broken

Webhook Payload Structure

Every delivery sends a JSON POST body with this structure:

{
  "event_type": "agent.tier.changed",
  "occurred_at": "2026-03-28T12:34:56.789Z",
  "data": {
    "tenant_id": "ten_abc123",
    "agent_id": "agt_xyz789",
    "previous_tier": "tier_1",
    "new_tier": "tier_2"
  }
}

The data field varies by event type. Headers include X-VeriSwarm-Signature, X-VeriSwarm-Timestamp, and X-VeriSwarm-Delivery-Id for verification and idempotency.

Delivery Lifecycle

Each webhook delivery goes through these states:

pending → delivered (2xx response)
        → failed (non-2xx or timeout)
            → retrying (up to 3 attempts)
                → delivered (retry succeeded)
                → exhausted (all retries failed)

Status	Meaning
`pending`	Delivery is queued
`delivered`	Your endpoint responded with 2xx
`failed`	Your endpoint returned non-2xx or the request timed out
`exhausted`	All retry attempts (3 total) have failed

Retry Policy

Failed deliveries are retried up to 3 attempts with exponential backoff:

Attempt	Delay
1st retry	~1 minute
2nd retry	~5 minutes
3rd retry	~15 minutes

Retries are processed by the webhook retry worker. You can also trigger retries manually via the API or the dashboard.

Circuit Breaker

If a webhook endpoint accumulates 10 consecutive failures, VeriSwarm automatically disables the endpoint to avoid wasting resources on a dead URL. The endpoint's is_active flag is set to false.

To re-enable a disabled endpoint, fix the underlying issue and then re-activate it from the dashboard or re-create it via the API.

Viewing Delivery History

Via the API

# All deliveries for your workspace
curl "https://veriswarm.ai/v1/public/providers/webhooks/deliveries?limit=50" \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

# Deliveries for a specific webhook endpoint
curl "https://veriswarm.ai/v1/public/providers/webhooks/deliveries?webhook_id=42&limit=50" \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Response:

[
  {
    "id": 1001,
    "webhook_id": 42,
    "event_type": "agent.scored",
    "status": "delivered",
    "status_code": 200,
    "duration_ms": 145,
    "error_message": null,
    "attempt_number": 1,
    "max_attempts": 3,
    "retried_from_delivery_id": null,
    "next_retry_at": null,
    "alert_sent_at": null,
    "alert_error": null,
    "created_at": "2026-03-28T12:34:56Z"
  }
]

Retrying Failed Deliveries

Manually retry a specific failed delivery (requires MFA):

curl -X POST https://veriswarm.ai/v1/public/providers/webhooks/deliveries/1001/retry \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Process all due retries in one batch:

curl -X POST "https://veriswarm.ai/v1/public/providers/webhooks/retries/run?limit=100" \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Get a retry summary:

curl https://veriswarm.ai/v1/public/providers/webhooks/retries/summary \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Rotating Signing Secrets

Rotate the signing secret for a webhook endpoint without recreating it. After rotation, you must update your verification code to use the new secret. Requires MFA.

curl -X POST https://veriswarm.ai/v1/public/providers/webhooks/42/rotate-secret \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Response:

{
  "status": "rotated",
  "webhook_id": 42,
  "signing_secret": "whsec_new_secret..."
}

Rotation strategy: To avoid dropped deliveries during rotation, temporarily accept both old and new secrets in your verification code, then remove the old secret once rotation is confirmed.

Testing Webhooks

Send a test delivery to verify your endpoint is reachable and correctly verifying signatures. Requires MFA.

curl -X POST https://veriswarm.ai/v1/public/providers/webhooks/42/test \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

This sends a sample decision.checked event with test data. The delivery is recorded in your delivery history like any real webhook.

Revoking a Webhook

Permanently disable a webhook endpoint. Requires MFA.

curl -X POST https://veriswarm.ai/v1/public/providers/webhooks/42/revoke \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Revoked webhooks stop receiving deliveries immediately. Existing pending retries for the endpoint are abandoned.

Listing All Webhooks

curl https://veriswarm.ai/v1/public/providers/webhooks \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Response:

[
  {
    "id": 42,
    "label": "Score Change Alerts",
    "callback_url": "https://api.example.com/webhooks/veriswarm",
    "event_types": ["agent.scored", "agent.tier.changed"],
    "is_active": true,
    "created_at": "2026-03-28T12:00:00Z",
    "last_attempted_at": "2026-03-28T14:30:00Z",
    "last_success_at": "2026-03-28T14:30:00Z",
    "last_status_code": 200
  }
]