{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"OpenAI API Platform 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":"openai-api-platform-integration","__idx":0},"children":["OpenAI API Platform Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Connect an OpenAI API project to Capsule Security to see what your applications and managed agents do on the OpenAI API: their prompts, responses, models and tool calls."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This integration is built on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.openai.com/api/docs/guides/webhooks"},"children":["OpenAI webhooks"]},". When you connect a project, Capsule uses your API key to register its own webhook endpoint on that project. OpenAI then notifies Capsule whenever a background response finishes or a managed agent session changes state, and Capsule reads the full object with the same key."]},{"$$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":"OpenAI events"},"children":["OpenAI events"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What Capsule records"},"children":["What Capsule records"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response.completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response.failed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response.incomplete"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response.cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A session with the input and assistant messages, reasoning summaries, tool calls (function, MCP and OpenAI-hosted tools) and errors. All responses of a project appear under one agent named ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OpenAI API"]},", linked to every model it calls."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent.session.created"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent.session.action_required"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent.session.idle"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent.session.failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One agent per managed agent, with its model, instructions and declared tools, and the activity of each of its sessions."]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Only background responses send webhooks."]}," OpenAI sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response.*"]}," events only for responses created with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["background: true"]},". Synchronous Responses API and Chat Completions calls are not visible through this integration. Capsule also needs the response to be stored, which is the default unless the request sets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["store: false"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An OpenAI organization with the API project you want to monitor"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Permission to create API keys in that project"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," account with admin access"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-create-a-project-api-key","__idx":3},"children":["Step 1: Create a Project API Key"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the OpenAI platform dashboard, open the project you want to connect."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a new secret key in the project's API keys settings."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Give the key access to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook endpoints"]}," (write), so Capsule can register its endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Responses"]}," (read)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Agents"]}," (read)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A key with all permissions also works."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Copy the key. OpenAI shows it only once."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-connect-in-capsule","__idx":4},"children":["Step 2: Connect in Capsule"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In Capsule, go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integrations"]}," and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OpenAI API Platform"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Paste the API key and click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test connection"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connect"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Capsule registers an endpoint named ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," in the project's webhook settings, subscribed to the events above. There is no URL or signing secret to copy."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To monitor more than one project, connect each project separately. OpenAI webhook endpoints belong to a single project."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-deliveries-are-secured","__idx":5},"children":["How Deliveries Are Secured"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Every delivery is checked against the endpoint's signing secret using the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.standardwebhooks.com"},"children":["Standard Webhooks"]}," scheme. Deliveries with a missing or invalid signature, or a timestamp more than five minutes off, are rejected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The endpoint URL carries a token that identifies your Capsule tenant. The token alone cannot be used to submit events, because a valid signature is also required."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Inline images and files, such as computer-use screenshots and generated images, are dropped before anything is stored."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API key is used only to manage Capsule's webhook endpoint and to read the responses and sessions that webhooks announce."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"disconnecting","__idx":6},"children":["Disconnecting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Removing the integration makes Capsule reject further deliveries. The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capsule Security"]}," endpoint stays on the OpenAI project, so delete it from the project's webhook settings as well."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":7},"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":"What to check"},"children":["What to check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test connection fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key is invalid or revoked. Create a new key."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test connection fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key cannot manage webhook endpoints. Grant it write access to webhook endpoints, or use a key with all permissions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No activity appears"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm your application creates responses with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["background: true"]}," and does not set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["store: false"]},". The endpoint's delivery log in the OpenAI dashboard shows whether OpenAI is sending events."]}]}]}]}]}]},"headings":[{"value":"OpenAI API Platform Integration","id":"openai-api-platform-integration","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Create a Project API Key","id":"step-1-create-a-project-api-key","depth":2},{"value":"Step 2: Connect in Capsule","id":"step-2-connect-in-capsule","depth":2},{"value":"How Deliveries Are Secured","id":"how-deliveries-are-secured","depth":2},{"value":"Disconnecting","id":"disconnecting","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2}],"frontmatter":{"seo":{"title":"OpenAI API Platform Integration"}},"lastModified":"2026-10-22T19:34:09.342Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/openai-platform","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}