---
title: "Find entity hook actions matching a request"
method: POST
path: "/entity_hook/action/find"
tags: ["Entity hook"]
---

# Find entity hook actions matching a request

`POST /entity_hook/action/find`

## Request

- Base URL: `https://api.nullplatform.com`
- URL: `https://api.nullplatform.com/entity_hook/action/find`
- Auth: HTTP bearer

Returns the entity hook actions that apply to a given NRN, action, dimensions, and an optional `request_body`.

Use this endpoint to discover, before mutating an entity, which hooks should fire and how to dispatch them (their `when`/`type` differ).

For each matching hook, the API runs a dry-run notification against the notifications service with `context.request_body` set to the supplied payload. Hooks whose dry-run finds no channel willing to deliver (channels with no `filters` match, or no subscribed channel at all) are excluded from the response. Hooks where at least one channel would deliver are included.

Response shape is the same as `GET /entity_hook/action`.

## Query parameters

- `offset` integer
- `limit` integer

## Request body

- EntityHookFind: Body for the `find` endpoint. nullplatform looks up hook actions that match the given NRN/action/dimensions, then runs a dry-run notification per matching hook against the notifications API with `request_body` included in the context. Only hooks whose dry-run resolves to at least one matching channel are returned — channels without matching filters cause their hook to be excluded.
  - `nrn` string, required: A resource identifier (NRN) specifying where this action applies.
  - `action` string, required: The specific action being performed on the entity.
  - `user_id` integer: Optional user identifier of the principal performing the action.
  - `dimensions` object: Key-value pairs defining the scope of the action.
  - `on` 'create' | 'update' | 'delete': Filters hooks that fire on this lifecycle event. Typically derived from the action verb.
  - `request_body` object: The payload of the originating request. Forwarded inside `context.request_body` when each matching hook's dry-run notification is sent, so that notification channels with `filters` can decide whether to deliver. Omit when you want to discover hooks without channel-side filtering.

## Response `200`

The list of entity hook actions that apply to the given context.

- EntityHookListResponse
  - `paging` object, required
    - `offset` integer, required: The starting point for pagination. Defaults to 0 if not provided.
    - `limit` integer, required: The maximum number of results to return per page. The maximum allowed value is 200.
  - `results` EntityHook[], required
    - `id` string, uuid, required: The unique identifier of the entity hook.
    - `nrn` string, required: A resource identifier (NRN) specifying where this action applies.
    - `entity` 'application' | 'scope' | 'deployment' | 'namespace', required: The type of entity affected by this entity hook action.
    - `action` 'deployment:create' | 'deployment:write' | 'deployment:delete' | 'scope:create' | 'scope:write' | 'scope:delete' | 'application:create' | 'application:write' | 'application:delete' | 'namespace:create' | 'namespace:write' | 'namespace:delete', required: The specific action you want to be notified about.
    - `dimensions` object: Key-value pairs defining the scope of the action.
    - `on_policy_success` 'manual', required: The action to be taken on the entity hook success. > **Note:** Currently, only "manual" is supported.
    - `on_policy_fail` 'manual', required: The action to be taken on entity hook failure." > **Note:** Currently, only "manual" is supported.
    - `when` 'before' | 'after', required: Specifies whether the hook occurs before or after nullplatform's internal logic.
    - `type` 'hook', required: The type of entity hook action. > **Note:** Currently, only "hook" is supported.
    - `on` 'create' | 'update' | 'delete', required: Specifies the type of action that triggers the hook.
    - `policies` object[]: The policies applied to the entity. > ℹ️ If no policies are found, we return an empty array.
      - `id` integer: A unique identifier for the policy.
      - `nrn` string: A resource identifier (NRN) specifying where the policy applies.
      - `name` string: The name of the policy.
      - `conditions` object: A JSON object defining the conditions under which this policy applies.

## Other responses

- `4XX`: The request couldn't be processed. For example, a parameter is invalid, the resource doesn't exist, or you don't have permission. The body is a problem details object (RFC 9457).
- `5XX`: Something went wrong on nullplatform's side. The body is a problem details object (RFC 9457).

## Changes

- **2026-10-15** `728d4df70ca1`: 6 breaking, 15 info
  - the response property `message` became optional for the status `4XX`
  - the response property `message` became optional for the status `5XX`
  - removed the required property `error` from the response with the `4XX` status
  - removed the required property `error` from the response with the `5XX` status
  - …17 more
- **2026-09-09** `ca82c7ad96be`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nullplatform/apis/nullplatform-api/changes/entity_hook/action/find/post.md)

---

[API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) - [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nullplatform/apis/nullplatform-api/revisions/d3f66bc633d4?raw)