Skip to content
Maintainer HQ

Hooks workspace

Hooks is an independent workspace surface, not a repository-only attachment. Owners enroll deployment-approved Hookrelay connections, operators review routing changes and retries, and viewers inspect metadata. Connections and individual subscriptions can be associated with a project that has no repository. Subscription associations override a connection's default project; selecting the connection default removes that override. HQ connection settings, project grouping, and repository links do not alter Hookrelay routes, destinations, queue policy, or event retention. Routing changes use the separate reviewed provider operation described below.

A subscription can also be explicitly linked to several repositories through the shared repository workspace contract. These links are independent of project grouping. The provider screen retains repository context and warns that an operation can affect other linked repositories. HQ captures the selected delivery's trusted subscription and its repository links before submitting a retry; later association edits do not rewrite that operation's Activity scope.

Browsing and freshness

The health summary reads a bounded latest-updated delivery sample and recent operational signals. Truncated samples explicitly exclude older history; zero sampled failures does not prove there are no older failures. Select the exhausted count to inspect all retained exhausted deliveries through bounded status-filtered pages, including records outside the sample. This clears any subscription filter so older failures are not hidden by that selection. Recent signals expose fixed codes, severity, occurrences, and first/last/resolved times, not provider exception text. An ingress rate-limit signal records a rejected request that exceeded the provider's traffic budget, not proof that delivery is down. The retention timestamp records a successful provider pass, not a guarantee about the presence of a particular event.

Deliveries use an indexed descending update-time cursor with event and sink tie-breakers. State filtering is indexed. Exact subscription filtering examines one bounded candidate page at a time, so an empty page can have a continuation. The browser preserves that Next action and calls the selection incomplete. Updates can move deliveries between pages; Refresh starts at the newest state rather than promising a frozen historical view. Subscriptions use bounded provider cursors and warn when records disappear during a read.

The filtering reason Recorded without notification means the source adapter retained the event but classified it as record-only instead of requesting notification delivery. It is not an HQ display filter or evidence of a failed delivery. The detail view explains that provider-owned decision without exposing the event payload.

While visible, the browser refreshes health and the first delivery page on the shared Hooks cadence. Deeper delivery pages do not poll automatically. Subscriptions have an explicit Refresh action. The Operations view reads HQ's bounded receipt history without polling provider health. These ordinary reads do not write provider status into HQ or imply fresh repository evidence. The separate repository coverage check retains minimized evidence about explicitly linked subscriptions: enabled configuration with a destination, not GitHub webhook installation or delivery success. Unavailable, disabled, unauthorized, malformed, and unsupported-version responses are not treated as empty healthy success. Failed refreshes remain visible alongside the prior read's timestamp. All displayed instants use account date/time preferences with exact UTC values retained in tooltips.

Subscription routing

In Subscriptions, choose Edit routing to change enabled state, select existing destinations, and configure subscription or per-destination event-type and severity filters. These controls change Hookrelay's provider-owned policy, not an HQ expectation or association. Empty filter fields impose no additional restriction; separate event types with commas and use exact lowercase types, prefixes ending in .*, or *. Exclusions take precedence. Destination filters apply in addition to subscription filters. Destination inventory is paginated; selected destinations remain in the draft across pages, and retired destinations cannot be added.

Choose Review changes to inspect the exact before/after policy, connection, subscription, provider revision, and expiry. This step saves a review without applying routing. Back to editing preserves the draft. Apply routing durably requests that reviewed change once. Disabling a subscription prevents its future ingress from routing; removing every destination leaves it unable to send notifications. Neither action cancels queued deliveries, replays retained events, changes the source adapter's record-only decisions, or installs, edits, or removes an upstream GitHub webhook. An accepted receipt proves configuration acceptance, not successful notification delivery.

The editor identifies the subscription by its stable provider resource UUID and binds every page and review to the configuration authority identity and revision. It never selects a mutation target by display name. Repository and project links remain HQ context keyed by subscription name; a display-name match is not evidence of one unique provider route. HQ captures the linked repository/project context before submission and retains that scope in subsequent outcome activity. Provider operations invalidate retained coverage for their connection so a prior configured-policy observation cannot remain fresh after routing changes.

Conflicts and failed reads preserve the draft. Load saved routing asks before replacing edits and only replaces them after a successful provider read. A changed connection or authority requires a fresh review. A lost review response can be retried with the same draft identity. After an interrupted Apply, inspect the saved operation; Reconcile with Hookrelay reads its original durable receipt without resending the change. The addressable review and Operations history support recovery after a reload. Open, pending, and indeterminate work is not success or definite failure. Reconcile unresolved work before preparing another change.

Read-only roles and provider credentials show View routing instead of an editable control. Unsupported or inactive providers retain the bounded legacy subscription view and an explicit availability notice. Online editing requires a compatible provider, an active configuration authority, and a separately granted configure capability; saving an HQ connection or deploying HQ grants none of these. Creation, destination provisioning, secret rotation, subscription retirement, and upstream webhook management are outside this policy editor. Do not describe it as full subscription lifecycle management.

Deliberate retries and recovery

Inspect one exhausted delivery, choose Review retry, and review the exact event, sink, generation, update timestamp, connection, and expiry before confirming. At-least-once delivery can produce duplicates. Hookrelay uses its sink configuration at execution time; review does not freeze that configuration. Pending or active deliveries remain under the provider's existing queue recovery.

Each saved review binds the workspace, original actor and credential, membership revision, connection revision, provider credential identity, and exact inputs. Only the original actor/credential can confirm. HQ persists operation intent before calling Hookrelay, rechecks live authority before submission, and never automatically retries a consequential call under a new plan. Hookrelay atomically accepts the exact exhausted generation and records a durable outbox transition and receipt. Queue acceptance is not delivery confirmation. A queue publication failure can leave accepted pending work for the existing scheduler to recover.

If a response or local receipt write is lost, keep the pending, running, or indeterminate operation and choose Reconcile with Hookrelay. Reconciliation reads the original provider receipt; it does not submit another retry. Any authorized workspace operator can reconcile, including after the HQ connection has been disabled. An open provider review remains uncertain while a request could be in flight. An expired unaccepted provider review establishes failure; an accepted receipt establishes provider acceptance, not later notification delivery. Disabling the HQ connection does not stop Hookrelay itself.

Changing a provider reference or rotating its identity must not silently redirect recovery. Retain the original scoped credential descriptor until uncertain operations are resolved, or deliberately restore its approved configuration. If the provider has pruned an old receipt, HQ cannot prove its outcome through this contract; retain the indeterminate record and investigate provider-owned evidence instead of inventing success or repeating the action. Review and receipt pages are addressable, and local operation history remains readable without an enabled provider connection.

Shared command contract

Browser, CLI, HTTP MCP, and stdio MCP use the same validated workspace service. Discover exact inputs with npm run cli -- schema <command> or MCP tool discovery:

  • Connections: hooks_connections, owner-only hooks_providers, hooks_connection_save
  • Metadata: hooks_snapshot, hooks_subscriptions, hooks_deliveries, hooks_delivery
  • Project grouping: hooks_association_get, hooks_association_save
  • Routing availability and reads: hooks_configuration, hooks_policy_subscriptions, hooks_policy_destinations, hooks_policy_subscription
  • Routing operations: hooks_policy_plan, hooks_policy_apply, hooks_policy_get, hooks_policy_reconcile
  • Delivery retries: hooks_retry_plan, hooks_retry_apply, hooks_retry_get, hooks_retry_reconcile
  • Workspace operation history: hooks_history, including the operation kind so clients open the correct routing or retry receipt

Ordinary metadata uses revision-aware Save/Cancel. Failed and conflicting saves preserve drafts; loading saved settings fetches the latest version and only replaces a draft after a successful read. Routing and retry clients retain the same review ID when recovering a lost planning response and the exact plan ID/fingerprint when confirming. Source-publisher and activity-reporter credentials have no Hooks authority. Reader automation can inspect metadata but cannot retry or change routing. Live provider reviews and unresolved operations block workspace transfers. All inputs are bounded and reject arbitrary provider URLs, SQL, paths, bindings, and secret values.

Provider deployment boundary

Hookrelay owns its versioned POST /admin/api/v1 contract and dedicated management credential catalog. Apply its management migration before deploying the compatible provider, then apply HQ's Hooks migration before deploying HQ. Both migrations are additive. Preserve private database checkpoints and the compatible prior artifacts; do not restore an old whole database over subsequent delivery or HQ work merely to roll back code.

HQ's reviewed release profile declares hookrelayBindings, each with a HOOKRELAY_ binding name and an exact provider Worker target. The server-side HOOKRELAY_CREDENTIALS secret maps opaque provider references to { workspaceId, name, binding, providerId, revision, token }. The provider separately holds only the token digest plus its ID, revision, workspace allowlist, capabilities, and expiry. read, retry, and configure are separate provider grants. Provision values through protected input and storage, not command arguments, ordinary UI forms, logs, or tracked files. The browser sees only safe reference names and configuration availability; the credential never enters browser state.

Online routing additionally depends on Hookrelay's additive configuration-authority migration and reviewed activation workflow. Before activation, quiesce legacy configuration writers, preserve a protected export and recovery artifact, inspect the exact authority revision and stable resource identities, and verify all required configuration writers use the active authority. Legacy setup, retirement, or rotation commands that have not been adapted must refuse rather than overwrite online policy. A stale file or deployment is not allowed to become a second configuration authority. Activation and credential grants require their own approved provider changes; an HQ deployment does not perform them. Preserve the active authority and private recovery exports when rolling back application code, rather than silently falling back to stale KV state.

Binding requests create their own credential headers and do not forward browser cookies or Access assertions. The only request destination is the fixed management path on the selected private binding, with redirects disabled. The client caps streamed response bytes and the complete header/body deadline, requires the supported version and strict metadata schemas, and discards raw provider error messages. The dedicated credential must not authorize Hookrelay's HTML administration or raw event handlers. Public management ingress retains the provider's existing protection; no new hostname, route, or preview is required.

Deployment verification must exercise real read-only metadata, denied anonymous/invalid-credential access, unchanged provider configuration, and exact HQ binding/Access placement. Apply HQ's policy-coverage migration before deploying the routing contract. It adds invalidation triggers without changing provider configuration. Do not retry a real notification or change a live policy as a smoke test. Isolated provider-runtime, service, and browser fixtures separately test policy and retry effects, failures, duplicates, revocation, reconciliation, and narrow-screen accessibility.

Resource and Free-plan considerations

HOOK_LIMITS defines bounded connections, provider references, page sizes, health samples, associations, pending reviews, response bytes, deadlines, and returned operation history. Indexed provider reads and per-actor pending-review limits contain individual request work; they are not a spending budget or an ingress rate limit. HQ metadata polling creates authenticated HQ and provider CPU work plus bounded D1/KV reads. It does not persist every successful read. Confirming a retry additionally uses durable database writes, retained-event checks, and the existing delivery queue, delivery attempt, and storage policies. CPU caps do not bound those downstream charges.

HOOK_POLICY_LIMITS bounds destinations, event patterns, and pattern length. Configuration availability is read for the Subscriptions view; policy details and one destination page are read when the editor is open. These queries share HQ's active-tab invalidation and do not add a polling timer. A review-expiry clock is browser-only. Planning persists a bounded review in HQ and Hookrelay; Apply writes HQ intent and the provider authority's atomic revision/receipt transaction; reconciliation reads a receipt and records the result in HQ. These operations consume database reads and writes, and provider receipt retention requires bounded cleanup. No combined Free-plan compatibility claim or exact spending ceiling follows from those bounds. The routing editor does not raise CPU limits, enable extra logging, or fan out new delivery jobs itself.

For Standard Workers pricing, service bindings do not add a separate request fee, but the combined CPU remains billable. Free-plan CPU compatibility of the combined authenticated HQ/provider path is unmeasured and must not be claimed from synthetic tests or from access to Workers Paid. Before advertising Free compatibility, measure that path against the provider and HQ request, CPU, database, KV, queue, storage, and logging allowances. Existing HQ collection overages and logging policy are documented in diagnostics. This integration does not enable provider-wide logging of sensitive ingress routes and does not implement automatic spending shutoff.