Webhooks

Use webhook destinations when another security system needs high-signal AgentKeeper events without polling. They are the right fit for blocked activity, MCP gateway decisions, investigation updates, workstation changes, and policy changes.

For historical sync and backfill, check the current Data API status in API Reference. For hook and collector ingestion, use Runtime Integration API.

Events

Delivery

AgentKeeper sends webhooks as JSON over HTTPS.

POST https://security.example.com/agentkeeper/webhooks
Content-Type: application/json
X-AgentKeeper-Event: activity.blocked
X-AgentKeeper-Delivery: deliv_01hzw4n
X-AgentKeeper-Timestamp: 2026-05-07T18:22:41.127Z
X-AgentKeeper-Signature: v1=<hmac-sha256>

Example payload:

{
  "schema_version": "agentkeeper.event.v1",
  "event_id": "runtime_events:evt_01hzw4n",
  "event_type": "activity.blocked",
  "severity": "high",
  "occurred_at": "2026-05-07T18:22:41.127Z",
  "detected_at": "2026-05-07T18:22:42.044Z",
  "org": {
    "id": "org_01hzw4k",
    "name": "Example Co"
  },
  "actor": {
    "email": "alex@example.com",
    "type": "user"
  },
  "host": {
    "hostname": "dev-laptop-01",
    "platform": "macos"
  },
  "session": {
    "id": "sess_01hzw4m"
  },
  "source": {
    "system": "runtime_shield",
    "table": "runtime_events",
    "id": "evt_01hzw4n"
  },
  "risk": {
    "verdict": "blocked",
    "category": "path_policy"
  },
  "evidence": {
    "title": "Runtime Shield blocked Bash",
    "summary": "Blocked by Runtime Shield path policy.",
    "details": {
      "tool_name": "Bash"
    }
  },
  "privacy": {
    "redacted": true,
    "excluded_fields": []
  },
  "delivery": {
    "destination_id": "dest_01hzw4n",
    "delivery_id": "deliv_01hzw4n"
  }
}

Signing

Every webhook should be signed with an endpoint-specific secret.

signed_payload = timestamp + "." + raw_body
signature = hex(hmac_sha256(endpoint_secret, signed_payload))

Consumers should reject deliveries when:

• The timestamp is outside a short tolerance window, usually five minutes
• The signature does not match
• The delivery ID was already processed

Retries

AgentKeeper records retryable delivery failures when the destination returns 408, 409, 429, any 5xx status, or a network timeout.

Permanent 4xx failures are not marked retryable except 408, 409, and 429.

Current retry scheduling is transient and short-lived:

Replay

Admins and owners can replay a delivery from Settings → Notifications → Deliveries when Notifications V2 storage is available in the environment.

There is no public Data API replay endpoint yet. Do not automate replay against /api/v1/webhook-deliveries/{id}/replay; that route is not implemented.

Recommended Destinations

When Not To Use Webhooks

Use a tenant-specific export contract or the Data API once enabled when you need:

• Full historical backfill
• Deterministic reconciliation
• Large result sets
• A daily warehouse sync
• Point-in-time exports for audit evidence