Webhook Events Integration
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Instrument any AI agent with Capsule Security's detection pipeline using a generic HTTP webhook interface for real-time prevention and observability.

Overview

The Webhook Events integration is a platform-agnostic HTTP API that lets you connect any AI agent — custom-built agents, orchestration frameworks, internal tools — to Capsule Security. Unlike IDE-specific integrations (Claude Code, Cursor, GitHub Copilot), this integration requires you to add HTTP calls directly in your agent code.

Two modes of operation are supported:

Prevention (synchronous) — your agent sends an event before executing an action and waits for an allow/block decision
Telemetry (asynchronous) — your agent fires an event after an action completes for observability, without blocking execution

Your Agent → HTTP POST → Capsule → Detection Pipeline → Allow/Block Response

Use this integration when:

You are building a custom AI agent or orchestration pipeline
Your platform does not have a native Capsule integration
You need programmatic control over when and how events are sent

Event Types

Blocking Events

Synchronous — your agent waits for an allow/block response before proceeding.

Event	Description
`tool_invocation`	Before a tool or action executes
`user_message`	Before a user prompt is processed

Observational Events

Fire-and-forget — Capsule responds with 202 Accepted.

Event	Description
`tool_result`	After tool execution completes
`agent_message`	Agent response text
`session_start`	Session begins
`session_end`	Session terminates

Prerequisites

Before you begin, ensure you have:

A Capsule Security account with admin access
An AI agent or application you want to instrument

Step 1: Generate API Credentials

Log in to the Capsule Security portal
Navigate to Integrations and locate Webhook Events
Click Install — Capsule generates a JWT token scoped to your tenant
Copy the token and store it securely (it will not be shown again)

Step 2: Instrument Your Agent

Add HTTP calls to your agent code at the appropriate lifecycle points. Refer to the API Reference and Integration Examples sections below.

API Reference

Endpoint

POST https://{capsule-host}/v1/generic-webhook/hooks/events

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <jwt-token>`
`x-correlation-id`	No	Trace ID for request correlation

Request Body

All events share a common envelope with event-specific fields.

`tool_invocation`

Sent before a tool executes. Blocks until Capsule responds.

{
  "event_type": "tool_invocation",
  "session_id": "sess-abc123",
  "timestamp": "2026-03-03T10:30:00Z",
  "agent": {
    "id": "support-agent",
    "name": "Customer Support Agent"
  },
  "user": {
    "email": "user@example.com"
  },
  "tool": {
    "name": "database_query",
    "input": { "query": "SELECT * FROM users" }
  }
}

`user_message`

Sent before a user prompt is processed. Blocks until Capsule responds.

{
  "event_type": "user_message",
  "session_id": "sess-abc123",
  "timestamp": "2026-03-03T10:30:00Z",
  "agent": {
    "id": "support-agent",
    "name": "Customer Support Agent"
  },
  "user": {
    "email": "user@example.com"
  },
  "message": {
    "content": "Show me all customer records from the last month"
  }
}

`tool_result`

Sent after tool execution completes. Fire-and-forget.

{
  "event_type": "tool_result",
  "session_id": "sess-abc123",
  "timestamp": "2026-03-03T10:30:05Z",
  "agent": {
    "id": "support-agent",
    "name": "Customer Support Agent"
  },
  "user": {
    "email": "user@example.com"
  },
  "tool": {
    "name": "database_query",
    "input": { "query": "SELECT * FROM users" },
    "output": { "row_count": 42 }
  }
}

`agent_message`

Sent after the agent produces a response. Fire-and-forget.

{
  "event_type": "agent_message",
  "session_id": "sess-abc123",
  "timestamp": "2026-03-03T10:30:06Z",
  "agent": {
    "id": "support-agent",
    "name": "Customer Support Agent"
  },
  "user": {
    "email": "user@example.com"
  },
  "message": {
    "content": "Here are the 42 customer records from the last month..."
  }
}

`session_start`

Sent when a session begins. Fire-and-forget.

{
  "event_type": "session_start",
  "session_id": "sess-abc123",
  "timestamp": "2026-03-03T10:29:55Z",
  "agent": {
    "id": "support-agent",
    "name": "Customer Support Agent"
  },
  "user": {
    "email": "user@example.com"
  }
}

`session_end`

Sent when a session terminates. Fire-and-forget.

{
  "event_type": "session_end",
  "session_id": "sess-abc123",
  "timestamp": "2026-03-03T10:45:00Z",
  "agent": {
    "id": "support-agent",
    "name": "Customer Support Agent"
  },
  "user": {
    "email": "user@example.com"
  }
}

Responses

Blocking Events (`tool_invocation`, `user_message`)

Allowed:

{
  "apiVersion": "1",
  "response": {
    "action": "allow"
  }
}

Blocked:

{
  "apiVersion": "1",
  "response": {
    "action": "block",
    "reason": "Policy violation: query accesses sensitive table"
  }
}

Observational Events

202 Accepted with an empty body.

Error Codes

Code	Meaning	Recommended Action
`400`	Malformed request body	Fix the payload and retry
`401`	Invalid or expired JWT	Regenerate credentials in the Capsule portal
`408`	Request timeout	Treat as allow (fail-open)
`500`	Server error	Treat as allow (fail-open)

Integration Examples

Pre-Execution Guard

Call tool_invocation before executing a tool. If the response contains "action": "block", deny the action.

curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "tool_invocation",
    "session_id": "sess-abc123",
    "timestamp": "2026-03-03T10:30:00Z",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"},
    "tool": {"name": "database_query", "input": {"query": "SELECT * FROM users"}}
  }'

Allowed response:

{
  "apiVersion": "1",
  "response": {
    "action": "allow"
  }
}

Blocked response:

{
  "apiVersion": "1",
  "response": {
    "action": "block",
    "reason": "Policy violation: query accesses sensitive table"
  }
}

Telemetry Reporter

Fire-and-forget tool_result after execution. Capsule responds with 202 Accepted.

curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "tool_result",
    "session_id": "sess-abc123",
    "timestamp": "2026-03-03T10:30:05Z",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"},
    "tool": {"name": "database_query", "input": {"query": "SELECT * FROM users"}, "output": {"row_count": 42}}
  }'

Full Session Lifecycle

A complete sequence showing all event types.

CAPSULE_URL="https://{capsule-host}/v1/generic-webhook/hooks/events"
TOKEN="your-jwt-token"
SESSION_ID="sess-$(uuidgen)"

# 1. Session start
curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "session_start",
    "session_id": "'"$SESSION_ID"'",
    "timestamp": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"}
  }'

# 2. User message (blocking)
curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "user_message",
    "session_id": "'"$SESSION_ID"'",
    "timestamp": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"},
    "message": {"content": "Look up order #12345"}
  }'

# 3. Tool invocation (blocking)
curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "tool_invocation",
    "session_id": "'"$SESSION_ID"'",
    "timestamp": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"},
    "tool": {"name": "order_lookup", "input": {"order_id": "12345"}}
  }'

# 4. Tool result (fire-and-forget)
curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "tool_result",
    "session_id": "'"$SESSION_ID"'",
    "timestamp": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"},
    "tool": {"name": "order_lookup", "input": {"order_id": "12345"}, "output": {"status": "shipped", "tracking": "1Z999AA10123456784"}}
  }'

# 5. Agent message (fire-and-forget)
curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "agent_message",
    "session_id": "'"$SESSION_ID"'",
    "timestamp": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"},
    "message": {"content": "Order #12345 has been shipped. Tracking number: 1Z999AA10123456784"}
  }'

# 6. Session end (fire-and-forget)
curl -X POST "$CAPSULE_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "session_end",
    "session_id": "'"$SESSION_ID"'",
    "timestamp": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
    "agent": {"id": "my-agent", "name": "My Agent"},
    "user": {"email": "user@example.com"}
  }'

Timeout and Reliability

Setting	Blocking Events	Telemetry Events
Server timeout	10s	10s
Recommended client timeout	10s	5s

Always fail-open: if Capsule is unreachable or returns a server error, allow the action to proceed. Telemetry failures must never block agent operation.

Verify the Integration

Send a session_start event followed by a tool_invocation event using the examples above
Log in to the Capsule Security portal
Navigate to Inventory > Agents and confirm your agent appears
Click on the agent and review the audit logs to verify events are captured
To view the full conversation, navigate to Observability and filter by Activity Type — Session

Troubleshooting

Symptom	Cause	Resolution
`401 Unauthorized`	Invalid or expired JWT	Regenerate credentials in Integrations → Webhook Events
Events not appearing in portal	Incorrect endpoint URL or malformed payload	Verify the URL and validate your JSON against the examples above
Blocking events always returning `allow`	No active policies configured	Configure detection policies in the Capsule portal
High latency on blocking events	Network distance to Capsule instance	Ensure your agent is in the same region as your Capsule deployment
`408 Request Timeout`	Capsule processing exceeded timeout	Your agent should treat this as `allow` (fail-open)

Security Considerations

Store JWT tokens in a secrets manager or environment variables — never hardcode them in source code
Use HTTPS exclusively — all Capsule endpoints require TLS
Rotate tokens periodically via the Capsule portal
Always fail-open — never let a dropped link to Capsule block your agent's operation

Support

For help with this integration, contact support.

References

JWT.io — debug and inspect JWT tokens

Webhook Events IntegrationCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Overview

Event Types

Blocking Events

Observational Events

Prerequisites

Step 1: Generate API Credentials

Step 2: Instrument Your Agent

API Reference

Endpoint

Headers

Request Body

tool_invocation

user_message

tool_result

agent_message

session_start

session_end

Responses

Blocking Events (tool_invocation, user_message)

Observational Events

Error Codes

Integration Examples

Pre-Execution Guard

Telemetry Reporter

Full Session Lifecycle

Timeout and Reliability

Verify the Integration

Troubleshooting

Security Considerations

Support

References

Was this helpful?

Webhook Events Integration
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

`tool_invocation`

`user_message`

`tool_result`

`agent_message`

`session_start`

`session_end`

Blocking Events (`tool_invocation`, `user_message`)