Custom App

A custom app is the starting point for your own integration: an internal tool, customer-facing product, automation service, or agent-capable app.

A custom app starts as an app record in Settings -> Apps. From there, add only the pieces your integration needs: OAuth, webhooks, API calls, SDK clients, or agent runtime support.

Use cases

You want to	Use
Add Log in with One Horizon to your product	OAuth Apps
Let customers connect a workspace to your product	OAuth Apps plus the REST API or JavaScript SDK
React when work, comments, or teams change	Webhooks
Sync work with an internal system	REST API or JavaScript SDK, usually with webhooks
Build an agent that accepts queued work	Choose how agents run

For internal automation in one workspace, start with API Keys. Choose OAuth when a person needs to approve access from their own account or when actions should be tied to a workspace member.

How the pieces fit

App record

The app record groups the integration setup in Settings -> Apps.

Create separate apps for staging and production. Keep callback URLs, client secrets, webhook keys, and delivery logs isolated by environment.

OAuth app

OAuth lets a workspace member approve your app. After approval, your backend can use user-scoped tokens to read workspace data or take actions the member is allowed to take.

OAuth fits Log in with One Horizon, Connect One Horizon, customer-facing integrations, MCP clients, and agent integrations. Keep callback, PKCE, client, and token details in OAuth Apps.

Webhooks

Webhooks notify your service when selected workspace events happen. They can start a sync, update another system, send a notification, or wake a cloud worker.

Webhooks covers delivery, verification keys, retries, CloudEvents, and delivery logs.

REST API and JavaScript SDK

The API reads or updates workspace data after OAuth approval, after a webhook event, or from a trusted backend job.

The REST API handles direct HTTP calls. The JavaScript SDK gives Node.js and TypeScript apps generated clients and types.

Agent runtime

Building an agent? Start by choosing how agents run. Agent docs cover local agents, cloud agents, sessions, claims, worker creation, and workflow execution.

Greenfield build order

Start with the product flow

Decide what your integration does before choosing APIs. A login flow, a workspace sync, a webhook receiver, and an agent worker all need different setup.

Create the app

Open Settings -> Apps and create a custom app for the integration. Add the app identity fields users will see during consent, especially the name, logo, homepage, privacy policy, and terms URL.

Add OAuth when users approve access

Add callback URLs and OAuth settings when your app needs Log in with One Horizon or Connect One Horizon. Store client secrets and tokens on the server, not in browser code.

Add webhooks when your service reacts to changes

Add an HTTPS webhook endpoint when your service should react to workspace events. Verify the endpoint, choose event types, and use delivery logs while testing.

Call the API for data and actions

Webhook events should stay small. The REST API or JavaScript SDK handles extra context, work updates, and write-backs.

Build the API layer

When the flow is clear, move from this page to the API reference for the exact calls and events your app needs.

Examples

The OAuth login example helps you test a login or connect flow before adding it to your product.

For webhook receivers, start from the template that matches your hosting target: Vercel, Netlify, Heroku, or Cloudflare Workers.