Runtime HTTP API.

TL;DR

The 30-second answer

A deployed HS-X Worker serves capability dispatch at POST /capabilities/<id>/invoke, HubSpot workflow actions at POST /workflow-actions/<id>/invoke (plus a /batched/invoke variant), card backends at POST /_hsx/cards/<id>, webhook triggers at POST /webhooks/hubspot/<id>, sync runs at POST /sync/<id>/run, the install OAuth pair at GET /oauth-start and GET /oauth-callback, and platform endpoints under /_hsx: health, manifest, flag evaluation, flag authoring, and the signed tenant-data read.

The surface splits into three auth models. Webhook triggers and workflow-action invokes are default-secure: whenever a HubSpot client secret is configured, a request without a valid HubSpot v3 signature is rejected with a 401. The tenant-data and flag-authoring endpoints take short-lived HMAC grants bound to the Worker's own identity. Everything else is an open JSON endpoint on the Worker's origin.

01 · Route map

Every route, one table

Three structural facts shape everything below. Each defineWorker(...) in your project deploys as its own Cloudflare Worker, so each origin serves this map for its own capabilities only; a capability id that lives on another worker is a 404 here. Routes that depend on optional wiring answer 409 with a *_not_configured error rather than pretending: sync_not_configured, batched_actions_not_configured, flags_not_configured, flags_authoring_not_configured, sync_read_not_configured. And every dispatch records a checkpoint on a linked deploy, which is what feeds hs-x logs and the dashboard; the observability reference covers that pipeline.

02 · Platform

Health and manifest

GET /_hsx/health answers with the Worker's name and the runtime version baked into it:

$ curl -s https://<worker>.workers.dev/_hsx/health
{"ok":true,"worker":"deals","runtimeVersion":"0.2.5"}

Health carries more weight than a liveness probe. Attestation heartbeats ride live requests: any incoming request, this one included, triggers an attestation send through ctx.waitUntil, throttled to one per 15 minutes per isolate. That is why hs-x deploy --promote-when-healthy pings /_hsx/health while it polls drift, and why a Worker that receives no traffic never attests; the deploy lifecycle reference covers the gate this feeds.

GET /_hsx/manifest returns the single worker's manifest: its name plus one entry per capability with kind, id, and the kind-specific fields (label, objectType, typed input/output field maps for tools; eventType and dedup for triggers; schedule, manageSchema, and the source for syncs; objectTypes for card backends). Note the shape difference from the local dev server, whose manifest wraps all of a project's workers in a workers array; here you are talking to exactly one.

03 · Invoke

Capability invokes and workflow actions

All three invoke routes accept the HS-X dispatch payload, every key optional:

{
  "input": { "threshold": 25000 },
  "enrolledObject": { "id": "d1", "objectType": "deals", "properties": { "amount": "50000" } },
  "install": { "id": "hubspot-app:123:portal:46993937", "portalId": "46993937", "state": "active", "config": {} }
}

A body that is not valid JSON, or that fails the dispatch-payload schema, is a 400 invalid_payload. A request without a content-type containing application/json is treated as an empty payload. The install block is what selects the portal whose stored OAuth token ctx.hubspot resolves.

POST /capabilities/<id>/invoke dispatches any capability the worker declares, whatever its kind. This is the route hs-x dev invoke <id> --remote posts to, and the production counterpart of the dev server's /_hsx/invoke/<id>. It is default-secure under the same policy as the workflow-action and webhook routes: once a signature secret is resolvable (an explicit runtime option or the HSX_HUBSPOT_CLIENT_SECRET binding), the route requires a valid HubSpot v3 signature and answers 401 otherwise. The install identity in the payload is caller-asserted, so the signature is what keeps a deployed Worker's stored install credentials from being exercised by arbitrary callers; hs-x dev invoke signs automatically with the secret from .dev.vars, and pre-OAuth bootstrap deploys, which have no secret yet, accept unsigned calls. Success is {"ok": true, "capabilityId": "<id>", "result": <handler result or null>}. A rate-limit backpressure result comes back the same way, as ok: true with the structured result; the rate-limits reference explains those shapes. An unhandled handler exception is recorded as an error checkpoint and rethrown, which the Workers platform surfaces as a 500.

A tool invoke that omits a required input field is rejected with 400 missing_required_input before the handler runs. Fields in a tool's input map that declare required: true (or HubSpot's legacy isRequired) and carry no default must be present and non-null; the response names the gaps:

{
  "ok": false,
  "error": "missing_required_input",
  "capabilityId": "tag-high-value-deals",
  "missing": ["threshold"],
  "message": "Missing required input field(s): threshold."
}

This check runs on all three invoke routes and applies only to tools; other capability kinds have no input field declarations to enforce.

POST /workflow-actions/<id>/invoke is the URL hs-x deploy writes into the workflow action's HubSpot metadata, so this is the route HubSpot's workflow engine actually executes. It answers only for tool capabilities (404 unknown_workflow_action otherwise) and accepts HubSpot's native execution body as well as the dispatch payload: input is read from inputFields, fields, or input; the record from object or enrolledObject; the portal id from portalId, portalID, or the origin block. The response speaks HubSpot's execution contract, mapped from the handler's ActionResult: ok answers 200 with outputFields built from the result's output (or data) record; fail-continue and block answer 200 with hs_execution_state set to FAIL_CONTINUE or BLOCK (the handler's message rides along as the hsx_message output field for executionRules); fail-stop answers 400, which HubSpot records as a failure without retrying; and retry-later answers 429 with a Retry-After header when the handler gave retryAfterSeconds, else 503 — both of which HubSpot requeues with exponential backoff for up to three days. The workflow actions guide covers the handler side.

POST /workflow-actions/<id>/batched/invoke is the deferred-completion variant: the payload must include input.callbackId (400 missing_callback_id otherwise), the handler result is enqueued for completion rather than returned, and the response is a 202 with {"ok": true, "capabilityId", "queued": true, "completionId", "shardId", "depth"}. A full queue shard also answers 202, with a retry-later backpressure result and queue.accepted: false. The route requires a completion queue in the runtime options; the entrypoint hs-x deploy generates does not wire one today, so on a standard deploy this route answers 409 batched_actions_not_configured.

Both workflow-action routes share the trigger routes' signature policy, which is the next section.

04 · Triggers

Webhook triggers and the v3 signature

POST /webhooks/hubspot/<id> dispatches a trigger capability (404 unknown_trigger for any other kind). The verification step runs before anything else touches the body.

The secret is resolved in a fixed order: an explicit webhook.hubSpotAppSecret in the runtime options wins, otherwise the HSX_HUBSPOT_CLIENT_SECRET binding that hs-x deploy pushes once the app's OAuth client secret is known. The same resolution backs the workflow-action routes. When no secret exists, which is the state of a pre-OAuth bootstrap deploy, unsigned requests are accepted because there is nothing to verify against; hs-x deploy warns loudly about that state.

When a secret is configured, the request must carry HubSpot's v3 signature headers, and four distinct 401s tell you exactly what failed:

The comparison is timing-safe, and the URL is decoded the way HubSpot encodes it before signing, so signatures verify byte-for-byte against what HubSpot sent.

Past the signature, the runtime derives a delivery id (from the x-hsx-delivery-id, x-hubspot-request-id, or x-hubspot-correlation-id header, falling back to the event id, a composite of subscription, object, and occurrence time, or a body hash) and drops repeats within a 24-hour window: {"ok": true, "capabilityId", "deduped": true, "deliveryId"}. On a deploy with the tenant database bound — any linked deploy with a data plane — the dedup store is durable: delivery ids are claimed atomically in tenant D1, so dedup: 'strict' holds across isolates, not just within one. Without the binding no dedup store is wired at all, and every signed delivery dispatches — design handlers on unlinked deploys to tolerate redelivery. When a trigger queue is configured, bursts are enqueued instead of executed inline, answering 202 with a jobId; the generated entrypoint wires no queue today, so a standard deploy executes triggers inline and answers {"ok": true, "capabilityId", "deliveryId", "result"}.

One half of this contract is still yours: HS-X owns the endpoint, but the webhook subscription in your app's configuration is declared by you, pointed at /webhooks/hubspot/<trigger-id>. The triggers guide walks through the pairing.

05 · Cards

Card backends and flag evaluation

POST /_hsx/cards/<id> dispatches a card-backend capability with the standard dispatch payload; it is the dispatch path the generated refs module exports for card frontends to call. The envelope matches the generic invoke: {"ok": true, "capabilityId", "result"}, with backpressure surfaced as a successful structured result. There is no signature model on this route.

POST /_hsx/flags/evaluate exists for cards that have no backend at all: the card iframe resolves feature flags against its own tenant Worker, reading the KV flag snapshots and running the same pure evaluator the runtime uses for ctx.flags. Neither the control plane nor HubSpot is in this read path.

// request
{ "flagKeys": ["new-pricing-table"], "targetingContext": { "portalId": "46993937" } }
 
// response
{ "ok": true, "flags": { "new-pricing-table": { "value": true, "variation": "on", "reason": "targeting_match" } } }

The request carries no per-key defaults; a missing or unreadable flag resolves to value: null with a fail-safe reason, and the caller overlays its own defaults. The Worker's baked-in identity (account, project, environment, app id) seeds the targeting context and the caller's targetingContext overlays it. The endpoint is unauthenticated and the targeting identity is caller-asserted; a cross-install session guard is deferred until a card-backend session model exists to verify against. On a deploy without the flags KV binding (any unlinked deploy) the route answers 409 flags_not_configured. The feature flags guide covers authoring and rollout rules.

06 · Sync

Sync runs, and who calls them

POST /sync/<id>/run executes one run of a sync capability: the runtime loads the stored cursor for the (capabilityId, portalId) pair, hands the handler a cursor context, persists the new cursor only if the handler set one, and answers with both facts:

{ "ok": true, "capabilityId": "import-orders", "cursorUpdated": true, "cursor": "2026-06-11T03:12:00Z", "result": null }

The portal id comes from the dispatch payload's install block and defaults to local-portal, so cursors are per-portal by construction.

There is no sync scheduler: nothing in HS-X calls /sync/<id>/run on a timer. A sync's schedule is declared in the manifest, but nothing consumes it yet: no scheduled handler is generated, no cron is attached to the Worker, and no platform component fires runs. The caller is you: CI, a cron you own, or the CLI during development. The route also requires a cursor store in the runtime options, which the generated entrypoint does not wire today, so on a standard deploy it answers 409 sync_not_configured; hand-wired runtimes supply their own store. The syncs guide covers cursor semantics end to end.

07 · OAuth

The install OAuth pair

These are the two routes HubSpot portals interact with when installing your app, and the only ones that answer with redirects and HTML pages rather than JSON.

GET /oauth-start mints a signed, five-minute state, then 302-redirects to HubSpot's authorize page with the Worker's own /oauth-callback as the redirect URI and the scopes from the HSX_HUBSPOT_SCOPES binding. It requires HSX_HUBSPOT_CLIENT_ID and configured state storage; a missing binding renders an "Install failed" page naming exactly which one.

GET /oauth-callback finishes the install. Two entry paths are legitimate, and the state rules differ on purpose. A self-initiated install arrives with the state /oauth-start minted, and a present-but-invalid state is rejected with a 400. A HubSpot-initiated install, from the app's Distribution tab or a marketplace listing, carries no state parameter at all, and proceeds on the authorization code alone; rejecting those would block every marketplace install, and the confidential code exchange is the proof of consent.

The exchange itself runs against HubSpot's date-based OAuth API (/oauth/2026-03/token), reads the portal id and scopes from the token response, and falls back to introspection only when they are absent. The runtime then writes two records to the tenant's own KV: the install owner record and the encrypted token blob that ctx.hubspot later resolves. On success the user is 302-redirected to the portal's connected-apps overview page. Failures render HTML pages with the failing step named: a 502 for an unreachable or failed exchange or introspection, a 500 when tokens were issued but could not be stored. The callback requires HSX_APP_ID, HSX_HUBSPOT_CLIENT_ID, HSX_HUBSPOT_CLIENT_SECRET, plus the token-storage bindings (HSX_TOKEN_KEY, INSTALL_KV) that hs-x deploy provisions.

08 · Grants

The signed-grant surfaces

Two route groups take a different credential entirely: a short-lived HMAC grant in the Authorization: Bearer header, signed with the per-install HSX_SYNC_GRANT_KEY secret provisioned at deploy. The grant is base64url(JSON claims).base64url(HMAC-SHA256); the claims carry the install identity (accountId, projectId, environment, hubSpotAppId), an enumerated scope list, issue and expiry timestamps, and a nonce. A grant is only honored when its identity claims equal the Worker's own baked-in identity, and it expires five minutes after issue by default. The failure ladder is precise: 401 unauthenticated with no bearer token, 401 invalid_grant for a bad signature or expired grant, 403 grant_binding_mismatch for the wrong install, 403 out_of_scope for a missing scope token.

POST /_hsx/sync/read is the tenant-data read-out: the path by which the control plane's sync worker reads installer users and platform-event occurrences out of the developer's own D1 to deliver them to a HubSpot CRM destination. The body is a discriminated selector over two resources and four modes:

All modes take an optional limit and answer {"ok": true, "resource", "rows"}. Windowed reads clamp since so a caller can only narrow, never widen, the replay window; the floor defaults to 90 days back, or the grant's own windowDays when it carries one. A grant that enumerates roles also caps which roles a by_role read may request. The endpoint and its signing client are live; the CRM sync app that would call it routinely is gated behind app-object approval, so nothing in the platform reads through it today.

POST /_hsx/flags/define and POST /_hsx/flags/list are the flag-authoring writes, behind the same grant machinery with the flags:write scope. This is what hs-x flags create, hs-x flags set-state, and hs-x flags list speak. Define is a full-definition upsert, last write wins: the body must be a complete flag definition whose identity equals the Worker's scope (403 identity_mismatch otherwise), the D1 config row is overwritten, and the project's flags are re-projected into the KV snapshots that /_hsx/flags/evaluate and ctx.flags read. The response is {"ok": true, "flag", "syncedSnapshots"}. There is no delete; archival is the kill switch, a PUT of the same definition with state: "archived", which the evaluator treats as serve-the-default. Both routes answer 409 flags_authoring_not_configured on deploys without the tenant D1 and flags KV bindings.

09 · Versus dev

How this differs from the local dev server

The local dev server (hs-x dev) and a deployed Worker dispatch through the same production router code, so a capability behaves identically in both. The HTTP wrapper around that router is different in shape:

The dev server serves exactly three endpoints, and none of the signed or HubSpot-facing surface; webhook signatures, OAuth installs, grants, and flag endpoints exist only on the deployed Worker. The local dev HTTP reference documents the dev side of this table.

Related

Related reference

• Local dev HTTP API — the three-endpoint dev-server counterpart of this surface.
• Deploy lifecycle — how attestation heartbeats riding these routes gate promotion.
• Observability — the checkpoint and Workers Logs pipeline every dispatch feeds.
• HubSpot API rate limits — the backpressure result shapes the invoke envelopes can carry.
• Triggers guide — pairing a HubSpot webhook subscription with /webhooks/hubspot/<id>.
• Workflow actions guide — the handler side of the action invoke routes.
• Feature flags guide — authoring the flags that /_hsx/flags/evaluate serves.

Last updated: June 11, 2026. Behavior reflects the runtime shipped with CLI v0.2.5, including the v3-signature fallback on webhook triggers and the missing_required_input contract on invoke routes. Refreshed when the route map or an auth model changes.