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 harness 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, JavaScript SDK, or Swift SDK
React when work, comments, or teams change	Webhooks
Sync work with an internal system	REST API, JavaScript SDK, or Swift SDK, usually with webhooks
Build an agent that accepts queued work	Building Agents

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.

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 harness 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.

How the pieces fit

App record

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

OAuth app

After a workspace member approves your app, your backend can use user-scoped tokens to read workspace data or take actions that member is allowed to take. Besides login and connect flows, OAuth fits customer-facing integrations, MCP clients, and agent integrations. OAuth Apps covers callback, PKCE, client, and token details.

Webhooks

A webhook event can start a sync, update another system, send a notification, or wake a cloud agent. Webhooks covers delivery, verification keys, retries, CloudEvents, and delivery logs.

REST API and SDKs

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, and the Swift SDK does the same for iOS and macOS.

Agent harness

Building an agent? Start with the Building Agents overview. The developer pages cover local and cloud agents, sessions, claims, registration, and the custom agent contract.

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.