Skip to content
Maintainer HQ

Hooks workspace

Hooks is a shared workspace surface, not a repository-only attachment. Owners enroll deployment-approved Hookrelay connections, operators review routing changes and retries, and viewers inspect metadata. Connections remain workspace-scoped so several projects can share one provider authority. Each subscription enrolled into HQ requires one explicit primary project, including a project that has no repository. A connection's optional project context is only a suggestion and does not assign its subscriptions. HQ connection settings, project ownership, 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.

Resolve hook expectations

Open Edit expectations on a repository and use the action beside Hook coverage. Set up coverage, Configure routing, Check coverage, and View coverage reflect saved evidence. The same flow is available for each selected repository in the project or workspace expectation editor and from a hook coverage gap.

Choose the Hookrelay connection, then Link subscription to associate an existing subscription or Configure routing to enable routing and select destinations. Shared subscriptions identify the other linked repositories affected by a routing edit. Check installation and delivery reads separate evidence for a stable provider resource. Existing subscriptions without provider setup metadata report installation as unverified.

Create subscription prepares a GitHub subscription for the repository's saved owner/repo identity. Choose a name, existing destinations and GitHub events, then Review setup. The review identifies the exact connection and choices. Apply setup creates provider routing, links the repository, assigns its project when the new subscription has no project, and installs a signed GitHub webhook. GitHub sends a setup ping; that ping is not notification delivery evidence. The provider requires an active configuration authority, a separate provision grant, and its own configured GitHub credential, setup key and ingress origin. Missing requirements are explained beside the disabled creation control. Destination provisioning remains a provider administrator operation.

The expectation draft stays open while you resolve coverage. Back to expectations restores its choices; Save changes saves those HQ assessment rules. Saving an expectation and applying provider setup have separate confirmation controls. Leaving an unsaved setup draft asks before discarding it. Repository and bulk expectation dialogs use dialog=expectations; resolve=hooks selects setup, and bulk setup also names resolveRepository. Connection, routing and saved setup review parameters preserve navigation context. These URLs reopen dialogs under normal workspace authorization. Unsaved form values stay in the tab and are not encoded in URLs. A saved setupReview reopens after reload and is also available from Hooks -> Operations.

Setup progress distinguishes routing configuration, the repository link, GitHub installation and observed delivery. A successful installation receipt is historical acceptance; Check verification reads provider state again. Delivery evidence covers a bounded recent event sample and never establishes continuous delivery health. Check coverage refreshes the separate repository assessment within its ordinary read limits.

If installation is rejected or fails before submission, the saved routing remains available. Review installation again reuses that subscription. After an interrupted installation, Reconcile setup reads the original receipt and GitHub state without another installation request. An absent webhook after an uncertain write does not authorize automatic resubmission. Keep the operation available for provider investigation if reconciliation remains indeterminate. A changed repository or connection can leave the HQ link pending even when installation succeeded; the receipt shows that partial outcome and the subscription can be linked through a fresh metadata edit.

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
  • GitHub setup: hooks_setup_configuration, hooks_setup_status, hooks_setup_plan, hooks_setup_apply, hooks_setup_get, hooks_setup_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 setup, 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, configure, and provision 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 all HQ migrations, including 0038_hook_setup_coverage.sql, before deploying the setup 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.

Operational dispositions

The shared browser command, CLI, and MCP contract includes hooks_signals, hooks_resolution_plan, hooks_resolution_get, hooks_resolution_apply, and hooks_resolution_reconcile. Signals are paginated with exact fingerprint, last-seen timestamp, and occurrence count. Exhausted deliveries retain their failed status and optional disposition metadata. Acknowledgement does not establish successful delivery.

Operational resolution requires HQ's operate capability and a separate provider resolve grant. Review up to one bounded page of exact signal or exhausted-delivery targets with a reason (recovered, obsolete, or accepted-loss) and a printable ASCII note without secret values or payloads. The review binds membership, token, actor, connection revision, provider identity, targets, and disposition. Apply stores operation intent before calling Hookrelay; uncertain responses require reconciliation through the original receipt. It never resends messages, removes history, or enables retention.

Deploy HQ's compatible response schemas before the provider adds disposition fields or receives a resolution grant. Provider migration and grant changes are explicit operational steps. Existing read-only clients remain unable to plan or apply resolutions.

The Hooks health view separates recent history from a complete summary of retained unresolved warning signals. History truncation alone does not add an attention coverage gap when the provider supplies that summary and the exhausted-delivery list is complete. A truncated exhausted list or older provider without complete unresolved-signal coverage keeps the gap visible. Acknowledged exhausted deliveries remain in history and do not become successful deliveries. Operational disposition entries in workspace history open their original receipt, reviewed reason, note, and exact record identities; the original operator can reconcile an uncertain acceptance without applying another disposition.