# OpenAI API Platform Integration

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.

## Overview

This integration is built on [OpenAI webhooks](https://developers.openai.com/api/docs/guides/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.

| OpenAI events | What Capsule records |
|  --- | --- |
| `response.completed`, `response.failed`, `response.incomplete`, `response.cancelled` | 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 **OpenAI API**, linked to every model it calls. |
| `agent.session.created`, `agent.session.action_required`, `agent.session.idle`, `agent.session.failed` | One agent per managed agent, with its model, instructions and declared tools, and the activity of each of its sessions. |


> **Only background responses send webhooks.** OpenAI sends `response.*` events only for responses created with `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 `store: false`.


## Prerequisites

- An OpenAI organization with the API project you want to monitor
- Permission to create API keys in that project
- A **Capsule Security** account with admin access


## Step 1: Create a Project API Key

1. In the OpenAI platform dashboard, open the project you want to connect.
2. Create a new secret key in the project's API keys settings.
3. Give the key access to:
  - **Webhook endpoints** (write), so Capsule can register its endpoint
  - **Responses** (read)
  - **Agents** (read)
A key with all permissions also works.
4. Copy the key. OpenAI shows it only once.


## Step 2: Connect in Capsule

1. In Capsule, go to **Integrations** and select **OpenAI API Platform**.
2. Paste the API key and click **Test connection**.
3. Click **Connect**.


Capsule registers an endpoint named **Capsule Security** in the project's webhook settings, subscribed to the events above. There is no URL or signing secret to copy.

To monitor more than one project, connect each project separately. OpenAI webhook endpoints belong to a single project.

## How Deliveries Are Secured

- Every delivery is checked against the endpoint's signing secret using the [Standard Webhooks](https://www.standardwebhooks.com) scheme. Deliveries with a missing or invalid signature, or a timestamp more than five minutes off, are rejected.
- 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.
- Inline images and files, such as computer-use screenshots and generated images, are dropped before anything is stored.
- The API key is used only to manage Capsule's webhook endpoint and to read the responses and sessions that webhooks announce.


## Disconnecting

Removing the integration makes Capsule reject further deliveries. The **Capsule Security** endpoint stays on the OpenAI project, so delete it from the project's webhook settings as well.

## Troubleshooting

| Symptom | What to check |
|  --- | --- |
| Test connection fails with `401` | The key is invalid or revoked. Create a new key. |
| Test connection fails with `403` | The key cannot manage webhook endpoints. Grant it write access to webhook endpoints, or use a key with all permissions. |
| No activity appears | Confirm your application creates responses with `background: true` and does not set `store: false`. The endpoint's delivery log in the OpenAI dashboard shows whether OpenAI is sending events. |