---
id: entity-hook-action-find
title: "Find entity hook actions matching a request"
description: "Returns the entity hook actions that apply to a given NRN, action, dimensions, and an optional `request_body`."
sidebar_label: "Find entity hook actions matching a request"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api/entity-hook
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Find entity hook actions matching a request"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/entity_hook/action/find"}
  context={"endpoint"}
>
  
</MethodEndpoint>



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`.


<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","name":"offset","schema":{"type":"integer","minimum":0,"default":0},"required":false,"description":"Pagination offset. Defaults to 0.","example":0},{"in":"query","name":"limit","schema":{"type":"integer","maximum":200,"default":30},"required":false,"description":"Pagination limit. Defaults to 30.","example":30}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["nrn","action"],"description":"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.","properties":{"nrn":{"type":"string","description":"A resource identifier (NRN) specifying where this action applies.","example":"organization=1:account=2:namespace=3:application=4"},"action":{"type":"string","description":"The specific action being performed on the entity.","example":"deployment:update"},"user_id":{"type":"integer","description":"Optional user identifier of the principal performing the action.","example":123},"dimensions":{"type":"object","description":"Key-value pairs defining the scope of the action.","example":{"environment":"production","country":"us"}},"on":{"type":"string","enum":["create","update","delete"],"description":"Filters hooks that fire on this lifecycle event. Typically derived from the action verb.","example":"update"},"request_body":{"type":"object","description":"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.","example":{"status":"finalized","traffic_percentage":100}}},"title":"entityHook_find"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of entity hook actions that apply to the given context.","content":{"application/json":{"schema":{"type":"object","required":["paging","results"],"properties":{"paging":{"type":"object","required":["offset","limit"],"properties":{"offset":{"type":"integer","minimum":0,"description":"The starting point for pagination. Defaults to 0 if not provided.","example":0},"limit":{"type":"integer","maximum":200,"description":"The maximum number of results to return per page. The maximum allowed value is 200.","example":200}}},"results":{"type":"array","items":{"type":"object","required":["id","nrn","entity","action","on_policy_success","on_policy_fail","when","type","on"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the entity hook.","example":"550e8400-e29b-41d4-a716-446655440000"},"nrn":{"type":"string","description":"A resource identifier (NRN) specifying where this action applies.","example":"organization=1:account=2:namespace=3:application=4"},"entity":{"type":"string","description":"The type of entity affected by this entity hook action.","enum":["application","scope","deployment","namespace"],"example":"scope"},"action":{"type":"string","description":"The specific action you want to be notified about.","enum":["deployment:create","deployment:write","deployment:delete","scope:create","scope:write","scope:delete","application:create","application:write","application:delete","namespace:create","namespace:write","namespace:delete"],"example":"scope:create"},"dimensions":{"type":"object","description":"Key-value pairs defining the scope of the action.","example":{"environment":"production","country":"us"}},"on_policy_success":{"type":"string","enum":["manual"],"description":"The action to be taken on the entity hook success.\n\n> **Note:** Currently, only \"manual\" is supported.\n","example":"manual"},"on_policy_fail":{"type":"string","enum":["manual"],"description":"The action to be taken on entity hook failure.\"\n\n  > **Note:** Currently, only \"manual\" is supported.\n","example":"manual"},"when":{"type":"string","enum":["before","after"],"description":"Specifies whether the hook occurs before or after nullplatform's internal logic.\n","example":"before"},"type":{"type":"string","enum":["hook"],"description":"The type of entity hook action.\n\n> **Note:** Currently, only \"hook\" is supported.\n","example":"hook"},"on":{"type":"string","enum":["create","update","delete"],"description":"Specifies the type of action that triggers the hook.","example":"create"},"policies":{"type":"array","description":"The policies applied to the entity.\n\n> ℹ️ If no policies are found, we return an empty array.\n","items":{"type":"object","properties":{"id":{"type":"integer","description":"A unique identifier for the policy.","example":5678},"nrn":{"type":"string","description":"A resource identifier (NRN) specifying where the policy applies.","example":"organization=1:account=2:namespace=3:application=4"},"name":{"type":"string","description":"The name of the policy.","example":"Crypto Kong Policies"},"conditions":{"type":"object","description":"A JSON object defining the conditions under which this policy applies.","example":{"scope.requested_spec.memory_in_gb":{"$lte":4}}}}}}},"title":"entityHook"}}},"title":"entityHookListResponse"}}}},"4XX":{"description":"Client error responses due to invalid input or missing parameters.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific client error (e.g., 400, 401, 403, 404).","example":400},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"bad_request"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Bad Request\", \"Unauthorized\").","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}}}}},"5XX":{"description":"Server error responses indicating an issue on the API side.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific server error (e.g., 500, 502, 503).","example":500},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"internal_server_error"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Internal Server Error\", \"Service Unavailable\").","example":"Internal Server Error"},"message":{"type":"string","description":"Additional details about the error.","example":"An unexpected error occurred. Please try again later."}}}}}}}}
>
  
</StatusCodes>