register_hook
Register shell commands, HTTP webhooks, or process signals that automatically trigger when secrets are written, deleted, or rotated to keep external systems in sync.
Instructions
[hooks] Register a side-effect (shell command, HTTP webhook, or process signal) that fires automatically when a matching secret is written, deleted, or rotated. Use to keep external systems in sync (restart a service after rotation, post to Slack on delete, kick a build); prefer agent_remember for storing facts an agent should recall later, and register_hook is not the right tool for time-based scheduled rotation (use agent_scan for that). Mutates the hook registry on disk. At least one match criterion (key, keyPattern, or tag) is required — calls without any return an error. Returns JSON of the registered hook entry including its assigned id (use that id with remove_hook).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Trigger only on this exact key name. Pick at most one of `key` / `keyPattern` / `tag` (or combine for stricter matching). | |
| tag | No | Trigger on any secret carrying this exact tag. Combinable with key/keyPattern as an AND filter. | |
| url | No | Required when type='http'. Full URL to POST a JSON body `{ id, key, scope, action, timestamp }` to (the value itself is never sent). | |
| type | Yes | Hook delivery mechanism. 'shell' runs a local command, 'http' POSTs JSON to a URL, 'signal' sends an OS signal to a named process. | |
| scope | No | Restrict the hook to secrets in this scope. Omit to fire across both global and project secrets. | |
| actions | No | Which lifecycle actions trigger this hook. Defaults to all three. | |
| command | No | Required when type='shell'. The literal shell command to run; q-ring exposes the matching key as $QRING_HOOK_KEY and action as $QRING_HOOK_ACTION. | |
| keyPattern | No | Trigger on any key matching this glob pattern. Examples: 'DB_*', 'STRIPE_*'. | |
| signalName | No | Signal name to send (e.g. 'SIGHUP', 'SIGUSR1'). Defaults to SIGHUP, which most daemons treat as 'reload config'. | SIGHUP |
| description | No | Free-text human-readable description, surfaced by `list_hooks` and the dashboard. | |
| signalTarget | No | Required when type='signal'. Either a numeric PID or a process name resolvable via `ps`. |