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

To add hooks to a plugin in the OpenAI Plugins repository, create a 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 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 (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 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, which serves as the canonical reference for hook implementation in this repository.

Step 2: Define Your Hook Objects

Each entry in 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 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:

{
  "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:

{
  "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 to register the hooks file:

{
  "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 demonstrating UI actions for design elements.
• plugins/<plugin-name>/.codex-plugin/plugin.json: The manifest that must reference hooks.json via the "hooks" field for the platform to recognize the definitions.
• .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: Documents the repository-wide hook support and required file layout (line 8).

Summary

• Create a 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 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 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 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 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 or plugins/my-plugin/hooks.json. The manifest at .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 scaffold script, this reference is automatically added to newly generated manifests, ensuring the marketplace scanner picks up your hooks during the next deployment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}