Skip to main content

Set up entity hooks

Setting up an entity hook involves three steps:

  1. Configure a notification channel.
  2. Create an entity hook action.
  3. Implement 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 POST request with the endpoint details.

Here's an example for an HTTP notification channel:

np notification channel create \
    --body '{
      "source": ["entity"],
      "nrn": "organization=1:account=2:namespace=3",
      "type": "http",
      "configuration": {
        "url": "https://yourdomain.com/url-you-configured"
      }
    }'

For more channel types and delivery options, 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 on an entity type. Create an entity hook action with the event and scope you want to subscribe to:

np entity-hook action create \
    --body '{
      "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 subscribe to (for example, application:create, scope:write, deployment:delete).
  • when: Whether the hook runs before or after nullplatform's internal processing.
  • type: The nature of the hook. Currently only hook is supported.
  • on: The lifecycle event that triggers the hook: create, update, or delete.

See the Entity hook API for the full parameter reference.

3. Implement hook processing​

Once the hook action is configured, nullplatform starts sending notifications to your channel. Each notification has this format:

POST https://yourdomain.com/url-you-configured
{
  "id": "1180cd02-1c36-4274-8e7a-4483b87e8f2e",
  "source": "entity",
  "event": "scope:create",
  "created_at": "2025-02-13T14:20:43.088Z",
  "notification": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entity": "scope",
    "entity_id": "5",
    "nrn": "organization=1:account=2:namespace=3:application=4:scope=5",
    "callback_url": "https://api.nullplatform.com/entity_hook/550e8400-e29b-41d4-a716-446655440000",
    "type": "hook",
    "when": "before",
    "on": "create"
  }
}

Responding to a hook​

note

You need an ops role to perform this action.

After processing the hook, send a PATCH request to the callback_url from the notification:

PATCH callback-url
{
  "status": "success",
  "messages": [
    {
      "level": "info",
      "message": "Information from the hook",
      "timestamp": 1740406453123
    },
    {
      "level": "warning",
      "message": "Warning report",
      "timestamp": 1740406527890
    },
    {
      "level": "error",
      "message": "The hook has failed",
      "timestamp": 1740406604567
    }
  ]
}

The status field controls how nullplatform handles the outcome:

StatusDescription
successHook logic executed successfully. The entity operation proceeds.
failedOperation failed entirely. The entity enters an error state.
recoverable_failurePartial failure. The entity remains valid but some changes may not have been applied. Relevant for update hooks.
cancelledEntity operation halted because conditions were not met.

The messages array is optional. Include it to give developers visibility into the hook's execution results.