Proxy Hooks

Proxy hooks intercept container traffic before it reaches the real service backend. Each hook binds an HTTP match (method, path, and optional headers) to a script that runs inside the container proxy. Within a service, hooks are evaluated in declared order and the first match wins. All write operations are gated by an If-Match: file:v<N> ETag precondition that the API returns from any successful read; this prevents lost updates when concurrent writers operate on the same hook list.

Use these endpoints when you want to register, reorder, update, or remove MITM hook scripts for a specific service running inside a container.

Listing hooks

`GET /api/v1/containers/{id}/proxy/hooks`

Returns all hooks grouped by service for the given container, along with the current file_version and etag that subsequent writes must echo back.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID

cURL
TypeScript SDK

curl -X GET "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.listContainerProxyHooks(containerId);

Response

{
  "statusCode": 200,
  "message": "Proxy hooks listed successfully",
  "data": {
    "hooks": {
      "auth": [
        {
          "id": "01h2x3y4z5a6b7c8d9e0f1g2h3",
          "position": 0,
          "match": {
            "method": "POST",
            "path": "/v1/login",
            "headers": {
              "content-type": "application/json"
            }
          },
          "script": {
            "subdomain": "audit",
            "path": "/scripts/log-auth.js"
          },
          "timeout": 1000,
          "applies_to": {
            "groups": ["audit"]
          }
        }
      ]
    },
    "file_version": 42,
    "etag": "file:v42"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

`GET /api/v1/containers/{id}/proxy/hooks/{service}`

Returns the ordered hook array for a single service. Within a service the order is significant because evaluation is first-match-wins.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`service`	path	string	Yes	Service name

cURL
TypeScript SDK

curl -X GET "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks/auth" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.listContainerProxyServiceHooks(containerId, 'auth');

Response

{
  "statusCode": 200,
  "message": "Service hooks listed successfully",
  "data": {
    "service": "auth",
    "hooks": [
      {
        "id": "01h2x3y4z5a6b7c8d9e0f1g2h3",
        "position": 0,
        "match": {
          "method": "POST",
          "path": "/v1/login"
        },
        "script": {
          "path": "/scripts/log-auth.js"
        },
        "timeout": 1000
      },
      {
        "id": "01h2x3y4z5a6b7c8d9e0f1g2h4",
        "position": 1,
        "match": {
          "method": "*",
          "path": "/v1/logout"
        },
        "script": {
          "path": "/scripts/log-logout.js"
        },
        "timeout": 500,
        "applies_to": {
          "groups": ["audit", "observability"]
        }
      }
    ],
    "file_version": 42,
    "etag": "file:v42"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

`GET /api/v1/containers/{id}/proxy/hooks/{service}/{hookId}`

Fetches a single hook by id within a service.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`service`	path	string	Yes	Service name
`hookId`	path	string	Yes	26-char Crockford base32 ULID (lowercase)

cURL
TypeScript SDK

curl -X GET "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks/auth/01h2x3y4z5a6b7c8d9e0f1g2h3" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.getContainerProxyHook(containerId, 'auth', '01h2x3y4z5a6b7c8d9e0f1g2h3');

Response

{
  "statusCode": 200,
  "message": "Hook retrieved successfully",
  "data": {
    "hook": {
      "id": "01h2x3y4z5a6b7c8d9e0f1g2h3",
      "position": 0,
      "match": {
        "method": "POST",
        "path": "/v1/login",
        "headers": {
          "content-type": "application/json"
        }
      },
      "script": {
        "subdomain": "audit",
        "path": "/scripts/log-auth.js"
      },
      "timeout": 1000,
      "applies_to": {
        "groups": ["audit"]
      }
    },
    "file_version": 42,
    "etag": "file:v42"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

Creating and modifying hooks

`POST /api/v1/containers/{id}/proxy/hooks/{service}`

Appends a new hook to the end of the service array, or inserts it at a specific position. Omit position to append. Requires an If-Match: file:v<N> header so that conflicting concurrent writers do not silently overwrite each other.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`service`	path	string	Yes	Service name
`if-match`	header	string	No	`file:v<N>` ETag precondition

Request Body

Field	Type	Required	Description
`match`	object	Yes	HTTP match — method, path, and optional headers
`script`	object	Yes	Script reference — `path` is required
`timeout`	integer	No	Hook execution budget in milliseconds (1-30000)
`applies_to`	object	No	Restrict hook to specific groups
`position`	integer	No	0-indexed insertion position (POST only)

cURL
TypeScript SDK

curl -X POST "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks/auth" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v42" \
  -d '{
    "match": {
      "method": "POST",
      "path": "/v1/login",
      "headers": { "content-type": "application/json" }
    },
    "script": {
      "subdomain": "audit",
      "path": "/scripts/log-auth.js"
    },
    "timeout": 1000,
    "applies_to": { "groups": ["audit"] }
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.addContainerProxyHook(
  containerId,
  'auth',
  {
    match: {
      method: 'POST',
      path: '/v1/login',
      headers: { 'content-type': 'application/json' }
    },
    script: {
      subdomain: 'audit',
      path: '/scripts/log-auth.js'
    },
    timeout: 1000,
    applies_to: { groups: ['audit'] }
  },
  { ifMatch: 'file:v42' }
);

Response

{
  "statusCode": 201,
  "message": "Hook created successfully",
  "data": {
    "hook": {
      "id": "01h2x3y4z5a6b7c8d9e0f1g2h3",
      "position": 0,
      "match": {
        "method": "POST",
        "path": "/v1/login"
      },
      "script": {
        "path": "/scripts/log-auth.js"
      },
      "timeout": 1000,
      "applies_to": {
        "groups": ["audit"]
      }
    },
    "file_version": 43,
    "etag": "file:v43"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

{
  "statusCode": 412,
  "error": "Precondition Failed",
  "message": "etag_mismatch"
}

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Invalid hook"
}

{
  "statusCode": 428,
  "error": "Precondition Required",
  "message": "If-Match header required for this operation"
}

`PUT /api/v1/containers/{id}/proxy/hooks/{service}/{hookId}`

Full-replaces a hook while preserving its id and position. Requires If-Match. The same path also accepts PATCH as a live alias, but the canonical verb is PUT.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`service`	path	string	Yes	Service name
`hookId`	path	string	Yes	26-char Crockford base32 ULID (lowercase)
`if-match`	header	string	No	`file:v<N>` ETag precondition

Request Body

Field	Type	Required	Description
`match`	object	Yes	HTTP match — method, path, and optional headers
`script`	object	Yes	Script reference — `path` is required
`timeout`	integer	No	Hook execution budget in milliseconds (1-30000)
`applies_to`	object	No	Restrict hook to specific groups
`position`	integer	No	0-indexed insertion position (POST only)

cURL
TypeScript SDK

curl -X PUT "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks/auth/01h2x3y4z5a6b7c8d9e0f1g2h3" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v43" \
  -d '{
    "match": {
      "method": "POST",
      "path": "/v1/session/login",
      "headers": { "content-type": "application/json" }
    },
    "script": {
      "subdomain": "audit",
      "path": "/scripts/log-session.js"
    },
    "timeout": 1500,
    "applies_to": { "groups": ["audit", "observability"] }
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.updateContainerProxyHook(
  containerId,
  'auth',
  '01h2x3y4z5a6b7c8d9e0f1g2h3',
  {
    match: {
      method: 'POST',
      path: '/v1/session/login',
      headers: { 'content-type': 'application/json' }
    },
    script: {
      subdomain: 'audit',
      path: '/scripts/log-session.js'
    },
    timeout: 1500,
    applies_to: { groups: ['audit', 'observability'] }
  },
  { ifMatch: 'file:v43' }
);

Response

{
  "statusCode": 200,
  "message": "Hook replaced successfully",
  "data": {
    "hook": {
      "id": "01h2x3y4z5a6b7c8d9e0f1g2h3",
      "position": 0,
      "match": {
        "method": "POST",
        "path": "/v1/session/login"
      },
      "script": {
        "path": "/scripts/log-session.js"
      },
      "timeout": 1500,
      "applies_to": {
        "groups": ["audit", "observability"]
      }
    },
    "file_version": 44,
    "etag": "file:v44"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

{
  "statusCode": 412,
  "error": "Precondition Failed",
  "message": "etag_mismatch"
}

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Invalid hook"
}

{
  "statusCode": 428,
  "error": "Precondition Required",
  "message": "If-Match header required for this operation"
}

`PATCH /api/v1/containers/{id}/proxy/hooks/{service}/{hookId}/position`

Performs an atomic move of a hook within its service array. The body is { position: N }. Requires If-Match.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`service`	path	string	Yes	Service name
`hookId`	path	string	Yes	26-char Crockford base32 ULID (lowercase)
`if-match`	header	string	No	`file:v<N>` ETag precondition

Request Body

Field	Type	Required	Description
`position`	integer	Yes	0-indexed target position in the service array

cURL
TypeScript SDK

curl -X PATCH "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks/auth/01h2x3y4z5a6b7c8d9e0f1g2h3/position" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "If-Match: file:v44" \
  -d '{ "position": 0 }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.moveContainerProxyHook(
  containerId,
  'auth',
  '01h2x3y4z5a6b7c8d9e0f1g2h3',
  { position: 0 },
  { ifMatch: 'file:v44' }
);

Response

{
  "statusCode": 200,
  "message": "Hook moved successfully",
  "data": {
    "hook": {
      "id": "01h2x3y4z5a6b7c8d9e0f1g2h3",
      "position": 0,
      "match": {
        "method": "POST",
        "path": "/v1/session/login"
      },
      "script": {
        "path": "/scripts/log-session.js"
      },
      "timeout": 1500
    },
    "file_version": 45,
    "etag": "file:v45"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

{
  "statusCode": 412,
  "error": "Precondition Failed",
  "message": "etag_mismatch"
}

{
  "statusCode": 428,
  "error": "Precondition Required",
  "message": "If-Match header required for this operation"
}

Deleting hooks

`DELETE /api/v1/containers/{id}/proxy/hooks/{service}`

Removes every hook under the named service. Returns the count of hooks removed and the new etag. Requires If-Match.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`service`	path	string	Yes	Service name
`if-match`	header	string	No	`file:v<N>` ETag precondition

This endpoint takes no request body.

cURL
TypeScript SDK

curl -X DELETE "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks/auth" \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v45"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.clearContainerProxyServiceHooks(containerId, 'auth', { ifMatch: 'file:v45' });

Response

{
  "statusCode": 200,
  "message": "Service hooks cleared successfully",
  "data": {
    "removed": 3,
    "file_version": 46,
    "etag": "file:v46"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

{
  "statusCode": 412,
  "error": "Precondition Failed",
  "message": "etag_mismatch"
}

{
  "statusCode": 428,
  "error": "Precondition Required",
  "message": "If-Match header required for this operation"
}

`DELETE /api/v1/containers/{id}/proxy/hooks/{service}/{hookId}`

Removes a single hook. The service’s remaining hooks retain their existing positions. Requires If-Match.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`service`	path	string	Yes	Service name
`hookId`	path	string	Yes	26-char Crockford base32 ULID (lowercase)
`if-match`	header	string	No	`file:v<N>` ETag precondition

This endpoint takes no request body.

cURL
TypeScript SDK

curl -X DELETE "https://api.hoody.com/api/v1/containers/{containerId}/proxy/hooks/auth/01h2x3y4z5a6b7c8d9e0f1g2h3" \
  -H "Authorization: Bearer <token>" \
  -H "If-Match: file:v46"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.proxyHooks.removeContainerProxyHook(
  containerId,
  'auth',
  '01h2x3y4z5a6b7c8d9e0f1g2h3',
  { ifMatch: 'file:v46' }
);

Response

{
  "statusCode": 200,
  "message": "Hook removed successfully",
  "data": {
    "file_version": 47,
    "etag": "file:v47"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`NOT_FOUND`	Hook or service not found	The hook id, service, or container does not exist, or the service is reject-listed	Verify the service name is not reject-listed (logs, proxy, workspaces, cdp) and that the hook id exists
`VALIDATION_ERROR`	Validation error	Request body violates hook schema, caps, or referential integrity	Check error details and correct the body shape; ensure applies_to.groups references defined groups
`PRECONDITION_REQUIRED`	If-Match required	Destructive writes require an `If-Match: file:v<N>` header	Fetch the resource first to obtain the ETag and resend with If-Match
`PRECONDITION_FAILED`	ETag mismatch	The If-Match header does not match the current file_version	Re-fetch the resource to get the current ETag and retry

{
  "statusCode": 412,
  "error": "Precondition Failed",
  "message": "etag_mismatch"
}

{
  "statusCode": 428,
  "error": "Precondition Required",
  "message": "If-Match header required for this operation"
}