# How to Add Hooks to a Plugin in the OpenAI Plugins Repository

> Learn how to add hooks to your OpenAI plugin by creating a hooks.json file and referencing it in your plugin.json manifest. Enhance your plugin's functionality seamlessly.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**To add hooks to a plugin in the OpenAI Plugins repository, create a [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file in your plugin directory, define your hook objects with `name`, `type`, and `entrypoint` fields, and reference the file in your [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest using the `"hooks"` key.**

Adding custom hooks to a plugin allows you to expose additional entry points—such as custom commands, webhook endpoints, or UI actions—without modifying the core skill code. In the `openai/plugins` repository, hooks are implemented via JSON configuration files that extend your plugin's capabilities according to the schema documented in the repository's [`README.md`](https://github.com/openai/plugins/blob/main/README.md) (line 8). This guide walks through the exact file structure, required schema, and manifest updates needed to register new hooks.

## What Are Plugin Hooks?

A hook in the OpenAI Plugins ecosystem is a JSON-encoded definition that registers new capabilities with the platform. Each hook specifies an identifier, execution type, and routing information that tells the platform how to invoke your code, whether through a Python skill script or an HTTP endpoint. The platform supports three distinct hook types—**`command`**, **`webhook`**, and **`ui`**—each routing events differently based on the `type` field.

## How to Add Hooks to a Plugin

### Step 1: Create the hooks.json Configuration File

Place a [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file at the top-level of your plugin directory. This file should sit alongside the `.codex-plugin` folder containing your manifest. For example, the Figma plugin defines its UI actions in [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json), which serves as the canonical reference for hook implementation in this repository.

### Step 2: Define Your Hook Objects

Each entry in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) must follow the repository schema with the following fields:

- **`name`**: The identifier used in workflows to trigger this hook (e.g., `"search_documents"`).
- **`type`**: One of `"command"`, `"webhook"`, or `"ui"`, determining how the platform routes events.
- **`description`**: Human-readable summary displayed in the marketplace.
- **`entrypoint`**: The skill path or URL route to invoke when the hook fires.
- **`payload_schema`**: Optional JSON-Schema describing expected input data for validation.

### Step 3: Reference hooks.json in plugin.json

The plugin manifest at `plugins/<plugin-name>/.codex-plugin/plugin.json` must include a `"hooks"` field pointing to your JSON file. The value should be a relative path such as `"./hooks.json"`. When scaffolding a new plugin, the script at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) automatically inserts this field into the generated manifest, ensuring the marketplace scanner detects your hooks on the next publish.

## Plugin Hook Configuration Examples

### Command Hook Definition

This configuration defines a command hook that invokes a Python script when triggered:

```json
{
  "hooks": [
    {
      "name": "search_documents",
      "type": "command",
      "description": "Searches the user's document library.",
      "entrypoint": "skills/document-search/scripts/search.py",
      "payload_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      }
    }
  ]
}

```

### Webhook Endpoint Definition

To receive external HTTP callbacks, define a webhook type hook with a URL path entrypoint:

```json
{
  "hooks": [
    {
      "name": "order_created",
      "type": "webhook",
      "description": "Receives order-creation events from the e-commerce platform.",
      "entrypoint": "/webhooks/order_created",
      "payload_schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "total": { "type": "number" }
        },
        "required": ["order_id", "total"]
      }
    }
  ]
}

```

### Plugin Manifest Configuration

Update your [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to register the hooks file:

```json
{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "Demo plugin with custom hooks",
  "hooks": "./hooks.json",
  "skills": ["skills/my-skill"]
}

```

## Where Hooks Are Defined in the Source Code

The OpenAI Plugins repository implements hook discovery through specific file paths that govern how the marketplace scanner ingests new capabilities:

- **`plugins/<plugin-name>/hooks.json`**: Contains the JSON definitions of custom hooks (command, webhook, or UI). The Figma plugin ships a real-world example at [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json) demonstrating UI actions for design elements.
- **`plugins/<plugin-name>/.codex-plugin/plugin.json`**: The manifest that must reference [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) via the `"hooks"` field for the platform to recognize the definitions.
- **[`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py)**: Scaffold script that auto-generates the `"hooks"` reference when creating new plugins, ensuring consistent file structure.
- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)**: Documents the repository-wide hook support and required file layout (line 8).

## Summary

- Create a [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file at your plugin root to define new entry points.
- Each hook requires `name`, `type`, and `entrypoint` fields, with optional `payload_schema` for input validation.
- Reference the hooks file in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) using the `"hooks"` key with a relative path like `"./hooks.json"`.
- Supported types include `"command"` for skill invocation, `"webhook"` for HTTP callbacks, and `"ui"` for interface actions.
- The plugin-creator scaffold at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) automatically configures the manifest reference when generating new plugins.

## Frequently Asked Questions

### What file format are plugin hooks defined in?

Hooks are defined in JSON format within a [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file located at the top-level of your plugin directory. The file must contain a top-level `"hooks"` array containing individual hook objects with specific schema requirements for `name`, `type`, and `entrypoint`.

### Where do I place the hooks.json file in my plugin?

Place [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) in the root of your plugin directory, at the same level as the `.codex-plugin` folder. For example, valid paths include [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json) or [`plugins/my-plugin/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/hooks.json). The manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) must reference this file using a relative path such as `"./hooks.json"`.

### What types of hooks are supported in the OpenAI Plugins repository?

The platform supports three hook types as implemented in the source code: `"command"` for invoking skill scripts, `"webhook"` for receiving HTTP POST requests, and `"ui"` for handling user interface interactions. Each type determines how the platform routes events to your specified `entrypoint`.

### How does the plugin manifest know where to find my hooks?

The manifest file at `plugins/<plugin-name>/.codex-plugin/plugin.json` must explicitly declare the location via a `"hooks"` field that points to your JSON definition file. When using the [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) scaffold script, this reference is automatically added to newly generated manifests, ensuring the marketplace scanner picks up your hooks during the next deployment.