Closes #20003: Introduce mechanism to register callbacks for webhook context (#20025)

* Closes #20003: Introduce mechanism to register callbacks for webhook context

* Swap ContentType with ObjectType

* Add plugin dev documentation for webhook callbacks

* Fix tests

* Add note about namespacing webhook data

docs/plugins/development/webhooks.md

@@ -0,0 +1,75 @@
+# Webhooks
+
+NetBox supports the configuration of outbound [webhooks](../../integrations/webhooks.md) which can be triggered by custom [event rules](../../features/event-rules.md). By default, a webhook's payload will contain a serialized representation of the object, before & after snapshots (if applicable), and some metadata.
+
+## Callback Registration
+
+Plugins can register callback functions to supplement a webhook's payload with their own data. For example, it might be desirable for a plugin to attach information about the status of some objects at the time a change was made.
+
+This can be accomplished by defining a function which accepts a defined set of keyword arguments and registering it as a webhook callback. Whenever a new webhook is generated, the function will be called, and any data it returns will be attached to the webhook's payload under the `context` key.
+
+### Example
+
+```python
+from extras.webhooks import register_webhook_callback
+from my_plugin.utilities import get_foo_status
+
+@register_webhook_callback
+def set_foo_status(object_type, event_type, data, request):
+    if status := get_foo_status():
+        return {
+            'foo': status
+        }
+```
+
+The resulting webhook payload will look like the following:
+
+```json
+{
+    "event": "updated",
+    "timestamp": "2025-08-07T14:24:30.627321+00:00",
+    "object_type": "dcim.site",
+    "username": "admin",
+    "request_id": "49e3e39e-7333-4b9c-a9af-19f0dc1e7dc9",
+    "data": {
+        "id": 2,
+        "url": "/api/dcim/sites/2/",
+        ...
+    },
+    "snapshots": {...},
+    "context": {
+        "foo": 123
+    }
+}
+```
+
+!!! note "Consider namespacing webhook data"
+    The data returned from all webhook callbacks will be compiled into a single `context` dictionary. Any existing keys within this dictionary will be overwritten by subsequent callbacks which include those keys. To avoid collisions with webhook data provided by other plugins, consider namespacing your plugin's data within a nested dictionary as such:
+    
+    ```python
+    return {
+        'my_plugin': {
+            'foo': 123,
+            'bar': 456,
+        }
+    }
+    ```
+
+### Callback Function Arguments
+
+| Name          | Type              | Description                                                       |
+|---------------|-------------------|-------------------------------------------------------------------|
+| `object_type` | ObjectType        | The ObjectType which represents the triggering object             |
+| `event_type`  | String            | The type of event which triggered the webhook (see `core.events`) |
+| `data`        | Dictionary        | The serialized representation of the object                       |
+| `request`     | NetBoxFakeRequest | A copy of the request (if any) which resulted in the change       |
+
+## Where to Define Callbacks
+
+Webhook callbacks can be defined anywhere within a plugin, but must be imported during plugin initialization. If you wish to keep them in a separate module, you can import that module under the PluginConfig's `ready()` method:
+
+```python
+def ready(self):
+    super().ready()
+    from my_plugin import webhook_callbacks
+```

mkdocs.yml

@@ -144,6 +144,7 @@ nav:
             - Search: 'plugins/development/search.md'
             - Event Types: 'plugins/development/event-types.md'
             - Data Backends: 'plugins/development/data-backends.md'
+            - Webhooks: 'plugins/development/webhooks.md'
             - User Interface: 'plugins/development/user-interface.md'
             - REST API: 'plugins/development/rest-api.md'
             - GraphQL API: 'plugins/development/graphql-api.md'

netbox/core/signals.py

@@ -136,7 +136,7 @@ def handle_changed_object(sender, instance, **kwargs):
 
     # Enqueue the object for event processing
     queue = events_queue.get()
-    enqueue_event(queue, instance, request.user, request.id, event_type)
+    enqueue_event(queue, instance, request, event_type)
     events_queue.set(queue)
 
     # Increment metric counters
@@ -220,7 +220,7 @@ def handle_deleted_object(sender, instance, **kwargs):
 
     # Enqueue the object for event processing
     queue = events_queue.get()
-    enqueue_event(queue, instance, request.user, request.id, OBJECT_DELETED)
+    enqueue_event(queue, instance, request, OBJECT_DELETED)
     events_queue.set(queue)
 
     # Increment metric counters

netbox/extras/events.py

@@ -2,18 +2,19 @@ import logging
 from collections import defaultdict
 
 from django.conf import settings
-from django.contrib.contenttypes.models import ContentType
 from django.utils import timezone
 from django.utils.module_loading import import_string
 from django.utils.translation import gettext as _
 from django_rq import get_queue
 
 from core.events import *
+from core.models import ObjectType
 from netbox.config import get_config
 from netbox.constants import RQ_QUEUE_DEFAULT
 from netbox.models.features import has_feature
 from users.models import User
 from utilities.api import get_serializer_for_model
+from utilities.request import copy_safe_request
 from utilities.rqworker import get_rq_retry
 from utilities.serialization import serialize_object
 from .choices import EventRuleActionChoices
@@ -50,7 +51,7 @@ def get_snapshots(instance, event_type):
     return snapshots
 
 
-def enqueue_event(queue, instance, user, request_id, event_type):
+def enqueue_event(queue, instance, request, event_type):
     """
     Enqueue a serialized representation of a created/updated/deleted object for the processing of
     events once the request has completed.
@@ -72,17 +73,19 @@ def enqueue_event(queue, instance, user, request_id, event_type):
             queue[key]['event_type'] = event_type
     else:
         queue[key] = {
-            'object_type': ContentType.objects.get_for_model(instance),
+            'object_type': ObjectType.objects.get_for_model(instance),
             'object_id': instance.pk,
             'event_type': event_type,
             'data': serialize_for_event(instance),
             'snapshots': get_snapshots(instance, event_type),
-            'username': user.username,
-            'request_id': request_id
+            'request': request,
+            # Legacy request attributes for backward compatibility
+            'username': request.user.username,
+            'request_id': request.id,
         }
 
 
-def process_event_rules(event_rules, object_type, event_type, data, username=None, snapshots=None, request_id=None):
+def process_event_rules(event_rules, object_type, event_type, data, username=None, snapshots=None, request=None):
     user = User.objects.get(username=username) if username else None
 
     for event_rule in event_rules:
@@ -105,7 +108,7 @@ def process_event_rules(event_rules, object_type, event_type, data, username=Non
             # Compile the task parameters
             params = {
                 "event_rule": event_rule,
-                "model_name": object_type.model,
+                "object_type": object_type,
                 "event_type": event_type,
                 "data": event_data,
                 "snapshots": snapshots,
@@ -115,8 +118,8 @@ def process_event_rules(event_rules, object_type, event_type, data, username=Non
             }
             if snapshots:
                 params["snapshots"] = snapshots
-            if request_id:
-                params["request_id"] = request_id
+            if request:
+                params["request"] = copy_safe_request(request)
 
             # Enqueue the task
             rq_queue.enqueue(
@@ -180,7 +183,7 @@ def process_event_queue(events):
             data=event['data'],
             username=event['username'],
             snapshots=event['snapshots'],
-            request_id=event['request_id']
+            request=event['request'],
         )
 
 

netbox/extras/tests/test_event_rules.py

@@ -135,7 +135,7 @@ class EventRuleTest(APITestCase):
         job = self.queue.jobs[0]
         self.assertEqual(job.kwargs['event_rule'], EventRule.objects.get(name='Event Rule 1'))
         self.assertEqual(job.kwargs['event_type'], OBJECT_CREATED)
-        self.assertEqual(job.kwargs['model_name'], 'site')
+        self.assertEqual(job.kwargs['object_type'], ObjectType.objects.get_for_model(Site))
         self.assertEqual(job.kwargs['data']['id'], response.data['id'])
         self.assertEqual(job.kwargs['data']['foo'], 1)
         self.assertEqual(len(job.kwargs['data']['tags']), len(response.data['tags']))
@@ -186,7 +186,7 @@ class EventRuleTest(APITestCase):
         for i, job in enumerate(self.queue.jobs):
             self.assertEqual(job.kwargs['event_rule'], EventRule.objects.get(name='Event Rule 1'))
             self.assertEqual(job.kwargs['event_type'], OBJECT_CREATED)
-            self.assertEqual(job.kwargs['model_name'], 'site')
+            self.assertEqual(job.kwargs['object_type'], ObjectType.objects.get_for_model(Site))
             self.assertEqual(job.kwargs['data']['id'], response.data[i]['id'])
             self.assertEqual(job.kwargs['data']['foo'], 1)
             self.assertEqual(len(job.kwargs['data']['tags']), len(response.data[i]['tags']))
@@ -218,7 +218,7 @@ class EventRuleTest(APITestCase):
         job = self.queue.jobs[0]
         self.assertEqual(job.kwargs['event_rule'], EventRule.objects.get(name='Event Rule 2'))
         self.assertEqual(job.kwargs['event_type'], OBJECT_UPDATED)
-        self.assertEqual(job.kwargs['model_name'], 'site')
+        self.assertEqual(job.kwargs['object_type'], ObjectType.objects.get_for_model(Site))
         self.assertEqual(job.kwargs['data']['id'], site.pk)
         self.assertEqual(job.kwargs['data']['foo'], 2)
         self.assertEqual(len(job.kwargs['data']['tags']), len(response.data['tags']))
@@ -275,7 +275,7 @@ class EventRuleTest(APITestCase):
         for i, job in enumerate(self.queue.jobs):
             self.assertEqual(job.kwargs['event_rule'], EventRule.objects.get(name='Event Rule 2'))
             self.assertEqual(job.kwargs['event_type'], OBJECT_UPDATED)
-            self.assertEqual(job.kwargs['model_name'], 'site')
+            self.assertEqual(job.kwargs['object_type'], ObjectType.objects.get_for_model(Site))
             self.assertEqual(job.kwargs['data']['id'], data[i]['id'])
             self.assertEqual(job.kwargs['data']['foo'], 2)
             self.assertEqual(len(job.kwargs['data']['tags']), len(response.data[i]['tags']))
@@ -302,7 +302,7 @@ class EventRuleTest(APITestCase):
         job = self.queue.jobs[0]
         self.assertEqual(job.kwargs['event_rule'], EventRule.objects.get(name='Event Rule 3'))
         self.assertEqual(job.kwargs['event_type'], OBJECT_DELETED)
-        self.assertEqual(job.kwargs['model_name'], 'site')
+        self.assertEqual(job.kwargs['object_type'], ObjectType.objects.get_for_model(Site))
         self.assertEqual(job.kwargs['data']['id'], site.pk)
         self.assertEqual(job.kwargs['data']['foo'], 3)
         self.assertEqual(job.kwargs['snapshots']['prechange']['name'], 'Site 1')
@@ -336,7 +336,7 @@ class EventRuleTest(APITestCase):
         for i, job in enumerate(self.queue.jobs):
             self.assertEqual(job.kwargs['event_rule'], EventRule.objects.get(name='Event Rule 3'))
             self.assertEqual(job.kwargs['event_type'], OBJECT_DELETED)
-            self.assertEqual(job.kwargs['model_name'], 'site')
+            self.assertEqual(job.kwargs['object_type'], ObjectType.objects.get_for_model(Site))
             self.assertEqual(job.kwargs['data']['id'], sites[i].pk)
             self.assertEqual(job.kwargs['data']['foo'], 3)
             self.assertEqual(job.kwargs['snapshots']['prechange']['name'], sites[i].name)
@@ -368,18 +368,23 @@ class EventRuleTest(APITestCase):
             self.assertEqual(body['request_id'], str(request_id))
             self.assertEqual(body['data']['name'], 'Site 1')
             self.assertEqual(body['data']['foo'], 1)
+            self.assertEqual(body['context']['foo'], 123)  # From netbox.tests.dummy_plugin
 
             return HttpResponse()
 
+        # Create a dummy request
+        request = RequestFactory().get(reverse('dcim:site_add'))
+        request.id = request_id
+        request.user = self.user
+
         # Enqueue a webhook for processing
         webhooks_queue = {}
         site = Site.objects.create(name='Site 1', slug='site-1')
         enqueue_event(
             webhooks_queue,
             instance=site,
-            user=self.user,
-            request_id=request_id,
-            event_type=OBJECT_CREATED
+            request=request,
+            event_type=OBJECT_CREATED,
         )
         flush_events(list(webhooks_queue.values()))
 

netbox/extras/webhooks.py

@@ -6,12 +6,28 @@ import requests
 from django_rq import job
 from jinja2.exceptions import TemplateError
 
+from netbox.registry import registry
 from utilities.proxy import resolve_proxies
 from .constants import WEBHOOK_EVENT_TYPES
 
+__all__ = (
+    'generate_signature',
+    'register_webhook_callback',
+    'send_webhook',
+)
+
 logger = logging.getLogger('netbox.webhooks')
 
 
+def register_webhook_callback(func):
+    """
+    Register a function as a webhook callback.
+    """
+    registry['webhook_callbacks'].append(func)
+    logger.debug(f'Registered webhook callback {func.__module__}.{func.__name__}')
+    return func
+
+
 def generate_signature(request_body, secret):
     """
     Return a cryptographic signature that can be used to verify the authenticity of webhook data.
@@ -25,7 +41,7 @@ def generate_signature(request_body, secret):
 
 
 @job('default')
-def send_webhook(event_rule, model_name, event_type, data, timestamp, username, request_id=None, snapshots=None):
+def send_webhook(event_rule, object_type, event_type, data, timestamp, username, request=None, snapshots=None):
     """
     Make a POST request to the defined Webhook
     """
@@ -35,9 +51,9 @@ def send_webhook(event_rule, model_name, event_type, data, timestamp, username,
     context = {
         'event': WEBHOOK_EVENT_TYPES.get(event_type, event_type),
         'timestamp': timestamp,
-        'model': model_name,
+        'model': object_type.model,
         'username': username,
-        'request_id': request_id,
+        'request_id': request.id if request else None,
         'data': data,
     }
     if snapshots:
@@ -45,6 +61,18 @@ def send_webhook(event_rule, model_name, event_type, data, timestamp, username,
             'snapshots': snapshots
         })
 
+    # Add any additional context from plugins
+    callback_data = {}
+    for callback in registry['webhook_callbacks']:
+        try:
+            if ret := callback(object_type, event_type, data, request):
+                callback_data.update(**ret)
+        except Exception as e:
+            logger.warning(f"Caught exception when processing callback {callback}: {e}")
+            pass
+    if callback_data:
+        context['context'] = callback_data
+
     # Build the headers for the HTTP request
     headers = {
         'Content-Type': webhook.http_content_type,

netbox/netbox/registry.py

@@ -34,5 +34,6 @@ registry = Registry({
     'system_jobs': dict(),
     'tables': collections.defaultdict(dict),
     'views': collections.defaultdict(dict),
+    'webhook_callbacks': list(),
     'widgets': dict(),
 })

netbox/netbox/tests/dummy_plugin/__init__.py

@@ -24,7 +24,7 @@ class DummyPluginConfig(PluginConfig):
     def ready(self):
         super().ready()
 
-        from . import jobs  # noqa: F401
+        from . import jobs, webhook_callbacks  # noqa: F401
 
 
 config = DummyPluginConfig

netbox/netbox/tests/dummy_plugin/webhook_callbacks.py

@@ -0,0 +1,8 @@
+from extras.webhooks import register_webhook_callback
+
+
+@register_webhook_callback
+def set_context(object_type, event_type, data, request):
+    return {
+        'foo': 123,
+    }

netbox/netbox/tests/test_plugins.py

@@ -10,6 +10,7 @@ from core.models import ObjectType
 from netbox.tests.dummy_plugin import config as dummy_config
 from netbox.tests.dummy_plugin.data_backends import DummyBackend
 from netbox.tests.dummy_plugin.jobs import DummySystemJob
+from netbox.tests.dummy_plugin.webhook_callbacks import set_context
 from netbox.plugins.navigation import PluginMenu
 from netbox.plugins.utils import get_plugin_config
 from netbox.graphql.schema import Query
@@ -220,3 +221,9 @@ class PluginTest(TestCase):
         Check that events pipeline is registered.
         """
         self.assertIn('netbox.tests.dummy_plugin.events.process_events_queue', settings.EVENTS_PIPELINE)
+
+    def test_webhook_callbacks(self):
+        """
+        Test the registration of webhook callbacks.
+        """
+        self.assertIn(set_context, registry['webhook_callbacks'])