Register (or replace) a hook at runtime, live immediately

Changed on
post/api/v1/admin/hooks

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header x-admin-token
    • HTTP bearer

Headers

If-Matchstring

Optimistic concurrency: the resource's ETag from a prior read (or the ETag returned by the previous mutation). Stale = 409 version_conflict (re-read and retry), nothing changes; absent or * = unconditional.

Request body

configobject required

A hooks: entry, as JSON. The accepted shape is the config file's own, documented in the configuration reference; it is not restated here because several of its types parse a wire shape that does not match their field layout.

namestring required

The hook name.

Response

Replaced: the name existed (same-grant re-register; body is the hook definition)

atstring nullable required

TAP observation stage ("request"/"candidate"/"routing"/"response"), or None for a gate.

globalboolean required

Whether this hook fires on every request (globally wired).

kindstring required

"tap" (fire-and-forget) or "gate" (fire-and-wait).

namestring required
on_errorstring required

Gate fallback on timeout/error, a CLOSED, unambiguous string union: one of the reserved terminals ("weighted" | "reject" | "first" | "nothing") or the NAME of the fallback hook the chain continues through. Unambiguous by construction: the terminal words are ILLEGAL hook names on every write path (config::RESERVED_HOOK_NAMES), so a value in the terminal set is always a terminal and anything else is always a hook reference.

priorityinteger required

Rewrite/reject ordering key (transform-chain order + reject tie-break).

promptstring required

Prompt access grant: "no" | "ro" | "rw".

settings_keysstring[] required

The KEY NAMES of the hook's opaque settings bag, sorted, WITHOUT their values, the same redacted projection [NamedDefView::settings_keys] carries, produced by the same helper.

This used to be the bag itself, under a doc comment claiming hook settings are "never a secret by contract". That claim was retracted for NamedDefView and it is no more true here: a hook's settings bag is a SecretRef carrier by design (hooks::HookEnv::resolve_hook_settings resolves it before every configure push), and config::secret::resolve_settings forwards a non-object bag verbatim, so a literal credential is fully supported too. GET /hooks and GET /hooks/{name} serve this at READ-ONLY admin scope. The values are readable only where they are writable: the config file and the config overlay.

timeout_msinteger required

Gate decision deadline in milliseconds.

userstring required

Caller-identity access grant: "no" | "ro".

Changes

  • 17d09470ca3bRevision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • 857732ef7bbeRevision changes
    • breaking

      added required request body

    • info

      api operation id PostHooks was added

    • info

      added the non-success response with the status