Event Rules
The plugin registers custom event types that can be used with NetBox's event rules to trigger webhooks, scripts, or other actions in response to change management activity.
Event Types
| Event Type | Description |
|---|---|
| Change request submitted | A change request's status has been set to Needs Review |
| Review submitted | A review has been submitted for a change request |
| Change request approved | A change request has met all policy requirements |
| Change request rejected | A change request has been rejected |
| Change request completed | The branch associated with a change request has been merged |
| Event retriggered | Events have been manually re-emitted for a change request via the retrigger API action |
How Events Reach External Systems
Change management activity flows through two separate paths: in-app notifications for the NetBox UI, and event rules for triggering webhooks and scripts.
Path 1: In-App Notifications
The five lifecycle event types listed above (change request submitted through change request completed) generate Notification records within NetBox. These appear in the notifications panel for relevant users (the CR owner and/or eligible policy reviewers, depending on the event). They do not trigger event rules, webhooks, or scripts.
These lifecycle event types are visible and selectable in the event rules configuration UI, but they are not emitted through the event processing pipeline. An event rule configured to trigger on one of these types will silently never fire. Use the standard object event types described below instead.
Path 2: Event Rules (Webhooks and Scripts)
To trigger webhooks or scripts in response to change request activity, create an event rule for the ChangeRequest object type using the standard object event types (object created, object updated, object deleted). These events fire through the core NetBox event processing pipeline whenever a ChangeRequest is saved or deleted.
Use event rule conditions to target specific lifecycle transitions. For example, a condition of {"status": "approved"} on an object updated event will match only when a change request reaches the approved state. See the Integration Guide for detailed configuration examples.
The event retriggered type also fires through this path. It is emitted when an administrator uses the retrigger button in the UI or calls the retrigger API action, and is useful when an external system missed or failed to process the original event.
Retrigger emits the event_retriggered event type, not the original lifecycle event type. External systems that handle retriggered events should account for this.
Webhook Callback Enrichment
When a webhook fires for a ChangeRequest object, the plugin automatically enriches the payload with information about the most recent change on the associated branch. This additional context appears under the context key in the webhook template variables.
| Field | Description |
|---|---|
context.last_branch_change.id | The ID of the most recent ObjectChange on the branch |
context.last_branch_change.time | ISO 8601 timestamp of the change |
context.last_branch_change.action | The action performed (create, update, or delete) |
context.last_branch_change.changed_object_type | The type of object that was changed (e.g., dcim.site) |
If the branch has no changes, context.last_branch_change will be null.
This enrichment applies to all ChangeRequest webhooks regardless of event type, including event_retriggered.
End-User Guide
This guide is for the two roles that take part in day-to-day change management: requesters, who stage changes in a branch and ask for review, and reviewers, ...
Integration Guide
This guide covers how to integrate NetBox change management with external systems using webhooks, scripts, and the REST API. For a general overview of the ch...