Table of Contents

Hooks

Last updated:

Hooks connect Oscova Agents to other systems. Use them when another app should start an Oscova task, or when Oscova should call another app during an agent run.

Note

An outbound hook is a command or HTTP call Oscova makes after a selected event. A task webhook is an inbound HTTP call another system makes to start an Oscova task.

Who can manage hooks

The Hooks settings APIs are administrator-only. The visible page combines three related areas:

  • Hook handlers for outbound command and HTTP handlers.
  • Task webhook API keys for callers that trigger tasks.
  • Outbound HTTP hook secrets for secret header values sent to external HTTP hook endpoints.

These are separate on purpose. An inbound API key authenticates a caller to Oscova. An outbound HTTP secret is used by Oscova when it calls another service.

Configure hook handlers

Select Add hook to create a handler. New hooks start as enabled HTTP hooks for User prompt submit, with Fail closed and a 10-second timeout.

The visual table lets you scan each handler's status, events, target, timeout, and actions. Use Edit to change a handler, Duplicate to copy a handler, and Delete to remove one from the draft.

The hook editor lets you set:

  • Name for the admin label.
  • Handler type as Command or HTTP.
  • Enable this hook to include or skip the handler.
  • Failure mode as Fail closed or Fail open.
  • Timeout seconds, accepted from 1 to 300.
  • Events that should call the handler.

Command hooks require Command. Working directory and one-argument-per-line Arguments are optional. Only an administrator can author them. Oscova starts the command directly in the host process, not in the agent's command sandbox. The command inherits Oscova's full host environment and receives the hook envelope through standard input and OSCOVA_HOOK_* environment variables.

Warning

Configuring a command hook grants script-level access to the machine under Oscova's account. Treat it like allowing an administrator-authored script to run, and configure only commands you trust.

HTTP hooks require an absolute URL. Static headers store plain header values in hook settings. Secret headers store only a header name and a selected outbound HTTP hook secret.

Hook payloads can contain prompt text, tool arguments, outcome metadata such as result kind or error details, task details, user IDs, and other run context. They do not include the tool's returned value. Treat every command and HTTP destination as a trusted recipient.

Confidential agents still fire configured hooks, but content fields are removed. Prompt hooks omit prompt_text and attachments. Tool hooks omit arguments, error_message, and reason. Task lifecycle hooks omit parameters, result_summary, and error. Identity, event, task, tool, status, trigger, and execution-kind fields remain available. An agent that cannot be resolved is treated as confidential rather than releasing content.

Select Save hooks to persist handler changes. Reset discards unsaved handler edits. The JSON tab lets you copy, paste, or inspect the handler list. Apply JSON validates and replaces only the draft. Click Save hooks afterward to persist it.

Choose failure behavior

Blocking events can stop the run. The blocking events are Task start, User prompt submit, and Before tool use. Session start, task completion or failure, and after-tool-use events are observe-only.

  • Fail closed denies a blocking event when the handler times out, exits unexpectedly, returns a non-success HTTP response, or otherwise fails.
  • Fail open lets a blocking event continue after those execution or transport failures.

Use Fail closed for policy checks. Use Fail open for logging, analytics, and notification hooks.

An explicit deny decision still denies a blocking event under either failure mode. Observe-only events never stop the run.

If Oscova cannot create the hook dispatcher or its service scope, no handler can be selected. Blocking events fail closed and observe-only events continue. This infrastructure failure takes precedence over every handler's failure mode.

Create task webhook API keys

Task webhook API keys let external systems call task webhook endpoints with Authorization: Bearer <token>.

When you create a key:

  • API key name is required.
  • Allowed task slugs is a comma-separated allowlist.
  • The token is shown once under Copy this token now.
  • The key receives the tasks:run scope.

Copy the token immediately. Later the UI shows only the prefix, created date, last-used date, scopes, and allowed slugs.

Use the key toggle to disable a caller without deleting it. Delete the key when the integration is gone.

Allowed task slugs are enforced on every webhook call. A key with the right tasks:run scope still cannot trigger a task whose slug is not in that key's allowed list. Leaving the list empty authorizes no tasks.

Webhook responses include a status URL for the run. External callers can poll that URL to read status, trigger source, and timestamps. Summary and error text are included only for runs stored as plain.

Store outbound HTTP hook secrets

Use Outbound HTTP hook secrets when an HTTP hook needs a header value that should not be stored directly in hook JSON.

The fields are:

  • Secret name for the friendly label.
  • Secret reference key for the stored credential key.
  • Secret value for the value sent as an HTTP header.
  • Description for admin notes.

If you leave Secret reference key blank, Oscova derives one from the secret name and adds a hook- prefix. New secrets require a value. Existing secrets can be edited with Secret value left blank to keep the stored value.

Deleting a secret fails when a saved hook still references it. Remove or change those secret headers first. If a referenced secret cannot be resolved during a hook call, Oscova omits that header.

Troubleshooting

  • Save hooks fails: check that every enabled handler has at least one event and the required command or absolute URL.
  • HTTP hook secret header fails validation: each header needs a name and selected secret. Duplicate header names are rejected.
  • API key creation fails: enter a non-blank name and check that allowed slugs are comma-separated.
  • A task webhook returns forbidden: the key must be enabled, include tasks:run, and allow the requested task slug.
  • A task webhook returns not found: the task must exist, be enabled, and have its external trigger enabled.