Integration runtime

Extend GitBook with custom components, event handling, OAuth flows, and HTTP

GitBook’s integration runtime is the platform that lets you build and run integrations within GitBook. Integrations can extend GitBook’s functionality by providing custom UI components, handling events, managing OAuth authentication, and communicating over HTTP.

The main building blocks are:

Building block	What it does
Integration initialization	Registers your integration.
UI components	Creates custom, interactive components.
OAuth handling	Manages authentication flows.
Environment context	Accesses runtime and installation details.
HTTP communication	Fetches external data using HTTP.
Actions and rendering	Defines component behavior and display.
Event handling	Listens and responds to GitBook events.
URL utilities	Works with URLs and query strings.

Create an integration

Integrations are created using the createIntegration() method. This method is the entrypoint for your integration and sets up its runtime context, including HTTP fetch methods, UI components, and event handlers.

export default createIntegration({
  fetch: async (request, context) => {
    // Process an HTTP request.
    return new Response(JSON.stringify({ message: "Hello World" }), {
      headers: { "Content-Type": "application/json" }
    });
  },
  components: [
    // A named component created using createComponent().
    myComponent
  ],
  events: {
    space_view: async (event, context) => {
      console.log("Space viewed:", event);
    },
  },
});

createIntegration() accepts the following object parameters:

Key	Type	Description
fetch	Async Function	A function to handle incoming HTTP requests or action dispatches.
components	Array	A list of UI component definitions created using createComponent().
events	Object	An object mapping event names to their handler functions.

Create a component

UI components let you build interactive elements that appear in GitBook’s quick insert menu (⌘ + /) or in the configuration screen of your integration. Use the createComponent() method to define a component’s identifier, initial state, actions, and rendering logic.

const myComponent = createComponent({
  componentId: "unique-id",
  initialState: (props) => ({ message: "Click me" }),
  action: async (element, action, context) => {
    switch (action.action) {
      case "say":
        return { state: { message: "Hello World" } };
      default:
        return {};
    }
  },
  render: async (element, context) => {
    return (
      <block>
        <button label={element.state.message} onPress={{ action: "say" }} />
      </block>
    );
  },
});

createComponent() accepts the following object parameters:

Key	Type	Description
componentId	string	Unique identifier for the component.
initialState	Function (props) ⇒ object	Function that initializes the component state based on its props.
action	Async Function	Callback that handles user interactions; receives element, action, and context.
render	Async Function	Function that returns the component’s UI as ContentKit markup.

Create an OAuth handler

When your integration requires user authentication via OAuth, you use createOAuthHandler() to define the OAuth flow. This function sets up redirection, token exchange, and extraction of credentials.

const oauthHandler = createOAuthHandler({
  redirectURL: `${environment.integration.urls.publicEndpoint}/oauth`,
  clientId: environment.secrets.CLIENT_ID,
  clientSecret: environment.secrets.CLIENT_SECRET,
  authorizeURL: "https://linear.app/oauth/authorize",
  accessTokenURL: "https://api.linear.app/oauth/token",
  extractCredentials: (response) => {
    if (!response.ok) {
      throw new Error(`Failed to exchange code for access token ${JSON.stringify(response)}`);
    }
    return {
      configuration: {
        oauth_credentials: { access_token: response.access_token },
      },
    };
  },
});

createOAuthHandler() accepts the following object parameters:

Parameter	Type	Description	Example Value
clientId*	string	Your client application ID from the OAuth provider.	"my-client-id"
clientSecret*	string	Your client secret from the OAuth provider.	"my-client-secret"
authorizeURL*	string	The URL where users are redirected for authorization.	"https://oauth.example.com/authorize"
accessTokenURL*	string	The URL used to exchange the authorization code for an access token.	"https://oauth.example.com/token"
redirectURL	string	(Optional) URL used for redirection if a static URL is needed.	"https://myapp.example.com/oauth"
scopes	string[]	An array of scopes to request during authentication.	["read", "write"]
prompt	string	(Optional) Configuration for prompting the user during authentication.	"consent"
extractCredentials	function	A function that processes the OAuth response and returns credentials in the expected format.	(response) => { … }

Rendering components

The render function returns the UI for the component using ContentKit markup.

render: async (element, context) => {
  return (
    <block>
      <button label={element.state.message} onPress={{ action: "say" }} />
    </block>
  );
},

Environment context

GitBook provides an environment object that gives your integration details about the runtime context, such as API endpoints, integration configuration, installation details, and secrets.

// Accessing environment values in your fetch or render method:
const { apiEndpoint, integration, secrets } = context.environment;
console.log("API endpoint:", apiEndpoint);

The context.environment object can include the following:

API information

Key	Type	Description
apiEndpoint	string	URL of the HTTP API.
apiTokens	object	Contains authentication tokens for the API.

Integration information

Key	Type	Description
integration	object	Details about the integration itself.

Site installation (if applicable)

Key	Type	Description
space	string	ID of the space where the integration is installed.
status	object	Installation status; e.g., Active, Pending, Paused.
configuration	object	Custom configuration variables for the space.
externalIds	any	External identifiers.
urls	object	Contains URLs associated with the installation (e.g., public endpoint).

Organization installation (if applicable)

Key	Type	Description
id	string	Installation ID.
space_selection	object	Specifies whether all spaces or selected spaces are used.
configuration	object	Custom configuration for the organization.
urls	object	Contains organization-related URLs.
externalIds	string[]	Array of external IDs assigned by the integration.
target	string	Target of the integration installation.

Runtime secrets

Key	Type	Description
secrets	object	Secrets stored on the integration for runtime use. Defined in the integration's configuration.

Events

GitBook fires events when specific actions occur (like viewing a page or updating content). Your integration can listen to these events to update state, log information, or trigger other actions.

Depending on the event, your integration may need the correct scope permissions.

Inside the createIntegration() call, you define event handlers:

export default createIntegration({
  events: {
    space_view: async (event, context) => {
      console.log("Space viewed event:", event);
    },
  },
});

Here are the available events you can read:

Event Name	Description
installation_setup	Triggered when the integration is first installed globally.
space_installation_setup	Triggered when the integration is installed into a specific space.
space_view	Triggered when a user views a space.
ui_render	Triggered when the integration's UI component is rendered.
space_content_updated	Triggered when content in the space is changed or updated.
space_visibility_updated	Triggered when a space's visibility settings are changed.
space_gitsync_started	Triggered when a Git sync process begins for a space.
space_gitsync_completed	Triggered when a Git sync process completes for a space.

Actions

Interactive components can respond to user events via actions. They are defined in your component when using createComponent().

action: async (element, action, context) => {
  // Process the action
  switch (action.action) {
    case "say":
      return { state: { message: "Hello World" } };
    default:
      return {};
  }
},

HTTP communication

Use the Fetch API to receive requests and call external services. Each integration installation has a public HTTPS endpoint at context.environment.integration.urls.publicEndpoint.

Receiving requests

GitBook receives requests at the versioned endpoint:

POST /{version}
Content-Type: multipart/form-data

GitBook manages endpoint versioning and backward compatibility. It normalizes the request envelope before it reaches your integration code.

The envelope contains these fields:

Field	Type	Description
event	Event	The trigger event, typed by @gitbook/api-client.
environment	object	The installation details and runtime context.
fetch-body	Buffer	The unmodified request body, when present. Use it for signature validation.

Use fetch-body for signed webhooks and non-JSON payloads. Verify a webhook signature before you process its event.

Sending requests

Pass these options when you create an outbound request:

Option	Type	Description	Example value
method	string	HTTP method, such as GET or POST.	"POST"
headers	object	HTTP headers as key-value pairs.	{ "Content-Type": "application/json" }
body	string	Payload to send with the request.	'{"message": "Hello World"}'

Handle a request

fetch: async (request, context) => {
  const data = { message: "Hello World" };
  return new Response(JSON.stringify(data), {
    headers: {
      "Content-Type": "application/json",
    },
  });
}

Create a request

const request = new Request("https://example.com", {
  method: "POST",
  body: '{"message": "Hello World"}',
});

Return a response

const handleFetchEvent = async (request, context) => {
  return new Response(JSON.stringify({ message: "Hello World" }), {
    headers: { "Content-Type": "application/json" }
  });
};

To implement a public endpoint, follow Handle an HTTP request. Learn more from the MDN Request documentation and MDN Response documentation.