Hooks

Hooks extend policy evaluation with data or logic unavailable in the standard policy input. Each hook receives the current policy input and returns JSON for Rego. Common use cases include:

Fetching a risk score from an internal service
Checking temporary approvals or maintenance windows
Adding business context from an existing API
Normalizing an external response into a stable object for policies

Hooks run in the access path. Keep their execution time and returned data as small as possible.

Writing Hooks

Hooks are written in JavaScript or TypeScript. The source must provide a default exported function, which may be synchronous or asynchronous.

type HookCache = {
  get(key: string): unknown;
  set(key: string, value: unknown, ttlSeconds: number): void;
};

export default async function hook(
  input: Readonly<Record<string, unknown>>,
  env: Readonly<Record<string, string>>,
  cache: HookCache,
): Promise<unknown> {
  return {};
}

The function accepts the following arguments:

Argument	Description
`input`	Policy input for the current evaluation stage
`env`	Allowed environment variables that are set on the evaluating endpoint
`cache`	Per-hook cache for JSON-compatible values

Only input is required. Hooks that do not use environment variables or caching may omit the other arguments. The return value must be representable as JSON. Objects, arrays, strings, numbers, booleans, and null are supported. The top-level value cannot be undefined, a function, or a symbol. Circular objects and bigint values are also unsupported. Imports are not supported. All required logic must be included in the hook source.

Status

Status	Behavior
Draft	Saved in Formal, but unavailable during policy evaluation
Active	Available to policies evaluated by Connectors and Endpoints

Use draft status while developing a hook. Activate it before creating or updating a policy that references it.

Policy Evaluation

Policies reference hook results through input.hooks.<name>. This policy blocks a request when the risk hook returns a score of 5 or greater:

package formal.v2

import future.keywords.if

request := {
  "action": "block",
  "type": "block_with_formal_message",
  "reason": "Request risk is too high"
} if {
  input.hooks.risk.score >= 5
}

Formal first evaluates the parts of each policy that do not depend on hooks. It then invokes only the hooks required to complete the policy decision. Each required hook receives the policy input for the current session, request, or response stage. Formal adds the returned value to input.hooks. It then completes the policy evaluation. Formal invokes a shared hook once when several applicable policies reference it. Hook references must use a fixed name. Both input.hooks.risk and input.hooks["risk"] are valid. Dynamic references such as input.hooks[hook_name] are not supported.

A policy can only reference an active hook. Formal rejects references to missing or draft hooks when validating the policy.

Complete Example

The following hook requests a risk score and caches the result for 60 seconds:

type PolicyInput = Readonly<{
  user: Readonly<{ email?: string }>;
  resource: Readonly<{ id: string }>;
}>;

type HookCache = {
  get(key: string): unknown;
  set(key: string, value: unknown, ttlSeconds: number): void;
};

export default async function hook(
  input: PolicyInput,
  env: Readonly<Record<string, string>>,
  cache: HookCache,
): Promise<unknown> {
  const cacheKey = `${input.user.email ?? "unknown"}:${input.resource.id}`;
  const cached = cache.get(cacheKey);

  if (cached !== undefined) {
    return cached;
  }

  const token = env["RISK_API_TOKEN"];
  if (!token) {
    throw new Error("RISK_API_TOKEN is not set");
  }

  const response = await fetch("https://risk.example.com/v1/score", {
    method: "POST",
    headers: {
      authorization: `Bearer ${token}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      user: input.user.email,
      resource: input.resource.id,
    }),
  });

  if (!response.ok) {
    throw new Error(`Risk service returned ${response.status}`);
  }

  const result = await response.json();
  cache.set(cacheKey, result, 60);
  return result;
}

This hook requires the following configuration:

Setting	Value
Allowed network hosts	`risk.example.com`
Allowed environment variables	`RISK_API_TOKEN`
Status	`active`

Network Access

Network access is denied by default. A hook can use fetch only for destinations included in its allowed network hosts. The allowlist accepts hostnames, IP addresses, and IP ranges in CIDR notation. Enter the destination without a scheme, path, or port. An allowed destination permits connections to all ports on that host or range. For example, allow risk.example.com rather than https://risk.example.com/v1/score.

Environment Variables

The env argument contains only variables named in the hook’s allowed environment variables. Formal omits allowed variables that are not set on the evaluating endpoint. No environment variables are available by default. Required variables must be configured on every Connector or Endpoint that may evaluate the hook.

A hook can send an allowed environment variable to an allowed network host. Only grant both capabilities when the hook requires them.

Caching

The cache argument stores JSON-compatible values between evaluations of the same hook. Each hook’s cache is isolated from other hooks.

const value: unknown = cache.get("key");
cache.set("key", { enabled: true }, 60);

cache.get(key) returns the stored value. It returns undefined when the key is missing or expired. cache.set(key, value, ttlSeconds) stores the value for the specified number of seconds. Writes are immediately visible to later reads during the same evaluation. To share cached values across multiple instances of the same Connector, enable clustering. Replication between instances is eventually consistent: an evaluation sees its own writes, but other Connector instances may not see them immediately. Cache availability and persistence failures do not fail an otherwise successful hook evaluations. Writes are applied after successful execution and failures are logged.

Caching is in-memory only and does not persist across Connector or Endpoint restarts. Cache entries may be unavailable or expire at any time. Treat the cache as an optimization rather than an authoritative data source.

Limits

Execution Limits

Limit	Value
Default timeout	5 seconds
Configurable timeout	Up to 60 seconds
Serialized output	1 MiB per evaluation
Network access	Denied by default; restricted to allowed hosts
Environment variables	None by default; restricted to allowed names
Imports	Not supported
Filesystem access	Not available

Cache Limits

Limit	Value
Key size	256 bytes
Serialized value size	4 KiB
Entries	1,024 per hook
Writes	1,024 distinct keys per evaluation
Total size	4 MiB per hook
Time to live	Up to 24 hours

Output and cache value limits use UTF-8 byte counts after JSON serialization. Cache key limits also use UTF-8 byte counts.

Errors

A hook evaluation fails when the hook:

Exceeds its configured timeout
Throws an error or returns a rejected promise
Attempts a network request to a destination that is not allowed
Returns a value that cannot be represented as JSON
Returns more than 1 MiB of serialized JSON
Exceeds a cache limit

When a required hook fails, the policy evaluation returns an error. Formal does not continue with an absent or partial hook result. Use explicit timeouts, handle upstream errors, and keep external dependencies reliable.

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Writing Hooks

Status

Policy Evaluation

Complete Example

Network Access

Environment Variables

Caching

Limits

Execution Limits

Cache Limits

Errors

Next Steps

Policy Evaluation

Policy Examples

​Writing Hooks

​Status

​Policy Evaluation

​Complete Example

​Network Access

​Environment Variables

​Caching

​Limits

​Execution Limits

​Cache Limits

​Errors

​Next Steps

Policy Evaluation

Policy Examples

Writing Hooks

Status

Policy Evaluation

Complete Example

Network Access

Environment Variables

Caching

Limits

Execution Limits

Cache Limits

Errors

Next Steps