---
title: "Respond to an entity hook"
method: PATCH
path: "/entity_hook/{id}"
tags: ["Entity hook"]
---

# Respond to an entity hook

`PATCH /entity_hook/{id}`

## Request

- Base URL: `https://api.nullplatform.com`
- URL: `https://api.nullplatform.com/entity_hook/{id}`
- Auth: HTTP bearer

Responds to an entity hook. Send this request to the `callback_url` from the hook notification once your logic has run.

The `status` you send decides how nullplatform resumes the entity operation. Add `callback_body` to hand fields back to the entity: they are merged into the update nullplatform sends when it resumes, so a before-hook on `application:create` can, for example, decide the repository the application is created in.

> ℹ️ **Note:** Only pending hooks can be updated. Fields nullplatform sets itself, such as the entity `status`, take precedence over `callback_body`.

## Path parameters

- `id` string, uuid, required

## Request body

- EntityHookRequestReply
  - `status` 'success' | 'failed' | 'recoverable_failure' | 'cancelled': The outcome of your hook logic. It decides how nullplatform resumes the entity operation: - `success`: the entity operation proceeds. - `failed`: the entity enters an error state. - `recoverable_failure`: partial failure. The entity remains valid but some changes may not have been applied. - `cancelled`: the operation is halted because conditions were not met.
  - `messages` EntityHookMessage[]: Optional messages that give developers visibility into the hook's execution results.
    - `level` 'info' | 'warning' | 'error', required: The severity of the message.
    - `message` string, required: A message shown to developers about the hook's execution.
    - `timestamp` integer: When the message was produced, as a Unix timestamp in milliseconds.
  - `callback_body` object: Fields to hand back to the entity. They are merged into the update nullplatform sends to the entity when it resumes the operation for the given `status`. Any field the entity's update endpoint accepts is allowed. Fields nullplatform sets itself, such as the entity `status`, take precedence. Must be a JSON object, otherwise the request is rejected with a `400` and the hook stays pending.

## Response `204`

The hook was updated and the callback for the given status was executed.

## 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/:id/patch.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)