Skip to main content

Entity hooks

What is an entity hook?​

Entity hooks allow you to define custom behavior during the lifecycle of your entities (applications, scopes, and deployments).

When you configure a hook, nullplatform ensures that you receive a notification for a specific event—such as the creation, update, or deletion of an entity—before the event is processed.

Your system is responsible for handling the notification and responding with the outcome of the custom logic. If no response is received, the entity will be blocked and will not proceed.

Entity hooks vs. approvals​

While both entity hooks and approvals help control entity lifecycle events, they serve different purposes:

  • Entity hooks enable automated, programmatic checks before an entity operation (create, update, delete) takes place. They ensure required preconditions, such as infrastructure setup, are met before proceeding.

  • Approvals enforce governance policies by requiring additional verification before certain actions are executed. They allow for decisions based on contextual metadata, such as blocking deployments during restricted periods. See Approvals for more information.

Using both entity hooks and approvals, organizations can automate workflows while maintaining control over critical processes.

During execution, approvals take precedence over hooks, meaning:

  • The approval request is sent first, leaving the hook pending the result.
  • Once the approval is granted, the hook is sent through the notification channel to execute the additional tasks.
  • If the approval is denied, the hook will not be sent and will remain in a cancelled state.

Common use cases​

Ensuring application configuration​

When creating an application, you may need to set up specific configurations (e.g., AWS accounts, Kubernetes clusters) to ensure future scopes and deployments function correctly.

By using a hook, you can enforce these configurations before the repository is created and before the application becomes available to developers. Without hooks, the application could become available before the required configurations are in place, potentially causing errors when creating scopes.

Some deployments require infrastructure that is not managed directly by nullplatform. For example, if a scope has a custom domain, a hook can verify that the domain exists and is properly configured before the deployment starts.

Setting up entity hooks​

Setting up an entity hook involves:

  1. Configuring a notification channel.
  2. Creating an entity hook action.
  3. Implementing the logic to process the hook and respond.

1. Configure a notification channel​

Hooks send notifications through the specialized entity feed. To receive these notifications, configure a notification channel by sending a send a POST request with the endpoint details.

Here's an example request for an HTTP notification channel:

curl -X POST "https://api.nullplatform.com/notification/channel" \
     -H "Content-Type: application/json" \  
     -d '{
        "source": ["entity"],
        "nrn":"organization=1:account=2:namespace=3",
        "type":"http",
        "configuration": {
            "url":"https://yourdomain.com/url-you-configured"
        }
     }'

For more info, see the Notifications documentation.

2. Create an entity hook action​

An entity hook action declares that you want to receive notifications for a specific event associated with an entity type.

To create an action, send a POST request to Create an entity hook action.

Request example:

curl -L -X POST 'https://api.nullplatform.com/entity_hook/action' \
        -H 'Content-Type: application/json' \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer <token>' \
        -d '{
          "nrn": "organization=1:account=2:namespace=3:application=4",
          "entity": "scope",
          "action": "scope:create",
          "dimensions": {
            "environment": "production",
            "country": "us"
          },
          "when": "before",
          "type": "hook",
          "on": "create"
        }'
Required parameters:
  • entity: The type of entity the hook applies to (application, scope, deployment).
  • action: The event to be notified about (e.g., application:create, scope:write, deployment:delete).
  • when: Specifies if the hook runs before or after nullplatform's internal processing. Currently, only before hooks are supported.
  • type: Defines the nature of the hook. Currently, only hook is supported.
  • on: Specifies which entity lifecycle event triggers the hook. (create, update, delete).

See the Entity hook API for more info.

3. Implement hook processing​

Once the hook action is set up, nullplatform will start sending hook notifications to your configured channel. These notifications follow this format:

POST https://yourdomain.com/url-you-configured
{
   "id":"<<notification-uuid>>",
   "source":"entity",
   "event":"scope:create",
   "created_at":"2025-02-13T14:20:43.088Z",
   "notification":{
      "id":"<<hook-uuid>>",
      "entity":"scope",
      "nrn":"organization=1:account=2:namespace=3:application=4:scope=5",
      "callback_url":"https://api.nullplatform.com/lifecycle_hook/<<hook-uuid>>",
      "type":"hook",
      "when":"before",
      "on":"create"
   }
}

Responding to a hook​

After processing the hook, send a response to the callback_url provided in the notification:

PATCH callback-url
{
    "status": "success",
    "messages": [
      {
         "level": "info", 
         "message": "Information from the hook"
      },
      {
         "level": "warning", 
         "message": "Warning report"
      },
      {
         "level": "error", 
         "message": "The hook has failed"
      }
    ]
}
Response status options
  • success: The hook logic was executed successfully.
  • failed: The operation failed entirely, causing the entity to enter an error state.
  • recoverable_failure: A partial failure occurred. The entity remains in a valid state but some actions may not have been applied. This status is relevant for update hooks, where a modification may not be applied, but the entity's previous state remains valid.
  • cancelled: The entity creation, update, or deletion is halted because conditions were not met.

You can also include optional messages to help developers understand the hook execution results.