{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhook Events Integration","description":"Control the power of AI Agents in runtime.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-events-integration","__idx":0},"children":["Webhook Events Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instrument any AI agent with Capsule Security's detection pipeline using a generic HTTP webhook interface for real-time prevention and observability."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Webhook Events integration is a platform-agnostic HTTP API that lets you connect ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two modes of operation are supported:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prevention"]}," (synchronous) — your agent sends an event ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["before"]}," executing an action and waits for an allow/block decision"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Telemetry"]}," (asynchronous) — your agent fires an event ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["after"]}," an action completes for observability, without blocking execution"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Your Agent → HTTP POST → Capsule → Detection Pipeline → Allow/Block Response\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this integration when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You are building a custom AI agent or orchestration pipeline"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your platform does not have a native Capsule integration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need programmatic control over when and how events are sent"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-types","__idx":2},"children":["Event Types"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"blocking-events","__idx":3},"children":["Blocking Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Synchronous — your agent waits for an allow/block response before proceeding."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_invocation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Before a tool or action executes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Before a user prompt is processed"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"observational-events","__idx":4},"children":["Observational Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fire-and-forget — Capsule responds with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["After tool execution completes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Agent response text"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session begins"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_end"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Session terminates"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":5},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you begin, ensure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," account with admin access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An AI agent or application you want to instrument"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-generate-api-credentials","__idx":6},"children":["Step 1: Generate API Credentials"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log in to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," portal"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integrations"]}," and locate ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook Events"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Install"]}," — Capsule generates a JWT token scoped to your tenant"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Copy the token and store it securely (it will not be shown again)"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-instrument-your-agent","__idx":7},"children":["Step 2: Instrument Your Agent"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add HTTP calls to your agent code at the appropriate lifecycle points. Refer to the API Reference and Integration Examples sections below."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-reference","__idx":8},"children":["API Reference"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint","__idx":9},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST https://{capsule-host}/v1/generic-webhook/hooks/events\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"headers","__idx":10},"children":["Headers"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer <jwt-token>"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-correlation-id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Trace ID for request correlation"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-body","__idx":11},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All events share a common envelope with event-specific fields."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"tool_invocation","__idx":12},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_invocation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," a tool executes. Blocks until Capsule responds."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event_type\": \"tool_invocation\",\n  \"session_id\": \"sess-abc123\",\n  \"timestamp\": \"2026-03-03T10:30:00Z\",\n  \"agent\": {\n    \"id\": \"support-agent\",\n    \"name\": \"Customer Support Agent\"\n  },\n  \"user\": {\n    \"email\": \"user@example.com\"\n  },\n  \"tool\": {\n    \"name\": \"database_query\",\n    \"input\": { \"query\": \"SELECT * FROM users\" }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"user_message","__idx":13},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_message"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["before"]}," a user prompt is processed. Blocks until Capsule responds."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event_type\": \"user_message\",\n  \"session_id\": \"sess-abc123\",\n  \"timestamp\": \"2026-03-03T10:30:00Z\",\n  \"agent\": {\n    \"id\": \"support-agent\",\n    \"name\": \"Customer Support Agent\"\n  },\n  \"user\": {\n    \"email\": \"user@example.com\"\n  },\n  \"message\": {\n    \"content\": \"Show me all customer records from the last month\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"tool_result","__idx":14},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_result"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["after"]}," tool execution completes. Fire-and-forget."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event_type\": \"tool_result\",\n  \"session_id\": \"sess-abc123\",\n  \"timestamp\": \"2026-03-03T10:30:05Z\",\n  \"agent\": {\n    \"id\": \"support-agent\",\n    \"name\": \"Customer Support Agent\"\n  },\n  \"user\": {\n    \"email\": \"user@example.com\"\n  },\n  \"tool\": {\n    \"name\": \"database_query\",\n    \"input\": { \"query\": \"SELECT * FROM users\" },\n    \"output\": { \"row_count\": 42 }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"agent_message","__idx":15},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent_message"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent after the agent produces a response. Fire-and-forget."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event_type\": \"agent_message\",\n  \"session_id\": \"sess-abc123\",\n  \"timestamp\": \"2026-03-03T10:30:06Z\",\n  \"agent\": {\n    \"id\": \"support-agent\",\n    \"name\": \"Customer Support Agent\"\n  },\n  \"user\": {\n    \"email\": \"user@example.com\"\n  },\n  \"message\": {\n    \"content\": \"Here are the 42 customer records from the last month...\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"session_start","__idx":16},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_start"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when a session begins. Fire-and-forget."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event_type\": \"session_start\",\n  \"session_id\": \"sess-abc123\",\n  \"timestamp\": \"2026-03-03T10:29:55Z\",\n  \"agent\": {\n    \"id\": \"support-agent\",\n    \"name\": \"Customer Support Agent\"\n  },\n  \"user\": {\n    \"email\": \"user@example.com\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"session_end","__idx":17},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_end"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sent when a session terminates. Fire-and-forget."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event_type\": \"session_end\",\n  \"session_id\": \"sess-abc123\",\n  \"timestamp\": \"2026-03-03T10:45:00Z\",\n  \"agent\": {\n    \"id\": \"support-agent\",\n    \"name\": \"Customer Support Agent\"\n  },\n  \"user\": {\n    \"email\": \"user@example.com\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"responses","__idx":18},"children":["Responses"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"blocking-events--tool_invocation--user_message-","__idx":19},"children":["Blocking Events (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_invocation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_message"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Allowed:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"apiVersion\": \"1\",\n  \"response\": {\n    \"action\": \"allow\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Blocked:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"apiVersion\": \"1\",\n  \"response\": {\n    \"action\": \"block\",\n    \"reason\": \"Policy violation: query accesses sensitive table\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"observational-events-1","__idx":20},"children":["Observational Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," with an empty body."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-codes","__idx":21},"children":["Error Codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recommended Action"},"children":["Recommended Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malformed request body"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the payload and retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or expired JWT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Regenerate credentials in the Capsule portal"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["408"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Treat as allow (fail-open)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Treat as allow (fail-open)"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-examples","__idx":22},"children":["Integration Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pre-execution-guard","__idx":23},"children":["Pre-Execution Guard"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_invocation"]}," before executing a tool. If the response contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"action\": \"block\""]},", deny the action."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"tool_invocation\",\n    \"session_id\": \"sess-abc123\",\n    \"timestamp\": \"2026-03-03T10:30:00Z\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"},\n    \"tool\": {\"name\": \"database_query\", \"input\": {\"query\": \"SELECT * FROM users\"}}\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Allowed response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"apiVersion\": \"1\",\n  \"response\": {\n    \"action\": \"allow\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Blocked response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"apiVersion\": \"1\",\n  \"response\": {\n    \"action\": \"block\",\n    \"reason\": \"Policy violation: query accesses sensitive table\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"telemetry-reporter","__idx":24},"children":["Telemetry Reporter"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fire-and-forget ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_result"]}," after execution. Capsule responds with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"tool_result\",\n    \"session_id\": \"sess-abc123\",\n    \"timestamp\": \"2026-03-03T10:30:05Z\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"},\n    \"tool\": {\"name\": \"database_query\", \"input\": {\"query\": \"SELECT * FROM users\"}, \"output\": {\"row_count\": 42}}\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"full-session-lifecycle","__idx":25},"children":["Full Session Lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A complete sequence showing all event types."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"CAPSULE_URL=\"https://{capsule-host}/v1/generic-webhook/hooks/events\"\nTOKEN=\"your-jwt-token\"\nSESSION_ID=\"sess-$(uuidgen)\"\n\n# 1. Session start\ncurl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"session_start\",\n    \"session_id\": \"'\"$SESSION_ID\"'\",\n    \"timestamp\": \"'\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"'\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"}\n  }'\n\n# 2. User message (blocking)\ncurl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"user_message\",\n    \"session_id\": \"'\"$SESSION_ID\"'\",\n    \"timestamp\": \"'\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"'\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"},\n    \"message\": {\"content\": \"Look up order #12345\"}\n  }'\n\n# 3. Tool invocation (blocking)\ncurl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"tool_invocation\",\n    \"session_id\": \"'\"$SESSION_ID\"'\",\n    \"timestamp\": \"'\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"'\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"},\n    \"tool\": {\"name\": \"order_lookup\", \"input\": {\"order_id\": \"12345\"}}\n  }'\n\n# 4. Tool result (fire-and-forget)\ncurl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"tool_result\",\n    \"session_id\": \"'\"$SESSION_ID\"'\",\n    \"timestamp\": \"'\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"'\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"},\n    \"tool\": {\"name\": \"order_lookup\", \"input\": {\"order_id\": \"12345\"}, \"output\": {\"status\": \"shipped\", \"tracking\": \"1Z999AA10123456784\"}}\n  }'\n\n# 5. Agent message (fire-and-forget)\ncurl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"agent_message\",\n    \"session_id\": \"'\"$SESSION_ID\"'\",\n    \"timestamp\": \"'\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"'\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"},\n    \"message\": {\"content\": \"Order #12345 has been shipped. Tracking number: 1Z999AA10123456784\"}\n  }'\n\n# 6. Session end (fire-and-forget)\ncurl -X POST \"$CAPSULE_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"event_type\": \"session_end\",\n    \"session_id\": \"'\"$SESSION_ID\"'\",\n    \"timestamp\": \"'\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"'\",\n    \"agent\": {\"id\": \"my-agent\", \"name\": \"My Agent\"},\n    \"user\": {\"email\": \"user@example.com\"}\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"timeout-and-reliability","__idx":26},"children":["Timeout and Reliability"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Setting"},"children":["Setting"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Blocking Events"},"children":["Blocking Events"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Telemetry Events"},"children":["Telemetry Events"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10s"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10s"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recommended client timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10s"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5s"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Always fail-open"]},": if Capsule is unreachable or returns a server error, allow the action to proceed. Telemetry failures must never block agent operation."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verify-the-integration","__idx":27},"children":["Verify the Integration"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session_start"]}," event followed by a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tool_invocation"]}," event using the examples above"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log in to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," portal"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inventory > Agents"]}," and confirm your agent appears"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click on the agent and review the audit logs to verify events are captured"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To view the full conversation, navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Observability"]}," and filter by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Activity Type — Session"]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":28},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Resolution"},"children":["Resolution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or expired JWT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Regenerate credentials in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integrations → Webhook Events"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Events not appearing in portal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Incorrect endpoint URL or malformed payload"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the URL and validate your JSON against the examples above"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blocking events always returning ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No active policies configured"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure detection policies in the Capsule portal"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["High latency on blocking events"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network distance to Capsule instance"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ensure your agent is in the same region as your Capsule deployment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["408 Request Timeout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Capsule processing exceeded timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your agent should treat this as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allow"]}," (fail-open)"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-considerations","__idx":29},"children":["Security Considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store JWT tokens in a secrets manager or environment variables — never hardcode them in source code"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use HTTPS exclusively — all Capsule endpoints require TLS"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rotate tokens periodically via the Capsule portal"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always fail-open — never let a dropped link to Capsule block your agent's operation"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":30},"children":["Support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For help with this integration, contact support."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"references","__idx":31},"children":["References"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://jwt.io"},"children":["JWT.io"]}," — debug and inspect JWT tokens"]}]}]},"headings":[{"value":"Webhook Events Integration","id":"webhook-events-integration","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Event Types","id":"event-types","depth":2},{"value":"Blocking Events","id":"blocking-events","depth":3},{"value":"Observational Events","id":"observational-events","depth":3},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Generate API Credentials","id":"step-1-generate-api-credentials","depth":2},{"value":"Step 2: Instrument Your Agent","id":"step-2-instrument-your-agent","depth":2},{"value":"API Reference","id":"api-reference","depth":2},{"value":"Endpoint","id":"endpoint","depth":3},{"value":"Headers","id":"headers","depth":3},{"value":"Request Body","id":"request-body","depth":3},{"value":"tool_invocation","id":"tool_invocation","depth":4},{"value":"user_message","id":"user_message","depth":4},{"value":"tool_result","id":"tool_result","depth":4},{"value":"agent_message","id":"agent_message","depth":4},{"value":"session_start","id":"session_start","depth":4},{"value":"session_end","id":"session_end","depth":4},{"value":"Responses","id":"responses","depth":3},{"value":"Blocking Events ( tool_invocation , user_message )","id":"blocking-events--tool_invocation--user_message-","depth":4},{"value":"Observational Events","id":"observational-events-1","depth":4},{"value":"Error Codes","id":"error-codes","depth":3},{"value":"Integration Examples","id":"integration-examples","depth":2},{"value":"Pre-Execution Guard","id":"pre-execution-guard","depth":3},{"value":"Telemetry Reporter","id":"telemetry-reporter","depth":3},{"value":"Full Session Lifecycle","id":"full-session-lifecycle","depth":3},{"value":"Timeout and Reliability","id":"timeout-and-reliability","depth":2},{"value":"Verify the Integration","id":"verify-the-integration","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"Security Considerations","id":"security-considerations","depth":2},{"value":"Support","id":"support","depth":2},{"value":"References","id":"references","depth":2}],"frontmatter":{"seo":{"title":"Webhook Events Integration"}},"lastModified":"2026-03-04T13:15:46.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/webhook-events","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}