diff --git a/docs/plugins/development/webhooks.md b/docs/plugins/development/webhooks.md new file mode 100644 index 0000000000..755d19d42a --- /dev/null +++ b/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 +``` diff --git a/mkdocs.yml b/mkdocs.yml index 585c8448c6..d427d3d240 100644 --- a/mkdocs.yml +++ b/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' diff --git a/netbox/core/signals.py b/netbox/core/signals.py index 0b8490dcb5..dff5571aba 100644 --- a/netbox/core/signals.py +++ b/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 diff --git a/netbox/extras/events.py b/netbox/extras/events.py index f8447fdb2a..9dac4ce450 100644 --- a/netbox/extras/events.py +++ b/netbox/extras/events.py @@ -2,18 +2,19 @@ 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'], ) diff --git a/netbox/extras/tests/test_event_rules.py b/netbox/extras/tests/test_event_rules.py index 2565e5bde9..0c9c25de32 100644 --- a/netbox/extras/tests/test_event_rules.py +++ b/netbox/extras/tests/test_event_rules.py @@ -135,7 +135,7 @@ def test_single_create_process_eventrule(self): 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 @@ def test_bulk_create_process_eventrule(self): 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 @@ def test_single_update_process_eventrule(self): 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 @@ def test_bulk_update_process_eventrule(self): 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 @@ def test_single_delete_process_eventrule(self): 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 @@ def test_bulk_delete_process_eventrule(self): 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 @@ def dummy_send(_, request, **kwargs): 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())) diff --git a/netbox/extras/webhooks.py b/netbox/extras/webhooks.py index 368075217d..1620d950e5 100644 --- a/netbox/extras/webhooks.py +++ b/netbox/extras/webhooks.py @@ -6,12 +6,28 @@ 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, diff --git a/netbox/netbox/registry.py b/netbox/netbox/registry.py index 02b7417795..fe5ce4301f 100644 --- a/netbox/netbox/registry.py +++ b/netbox/netbox/registry.py @@ -34,5 +34,6 @@ def __delitem__(self, key): 'system_jobs': dict(), 'tables': collections.defaultdict(dict), 'views': collections.defaultdict(dict), + 'webhook_callbacks': list(), 'widgets': dict(), }) diff --git a/netbox/netbox/tests/dummy_plugin/__init__.py b/netbox/netbox/tests/dummy_plugin/__init__.py index 2ca7c290c6..01eb0baa54 100644 --- a/netbox/netbox/tests/dummy_plugin/__init__.py +++ b/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 diff --git a/netbox/netbox/tests/dummy_plugin/webhook_callbacks.py b/netbox/netbox/tests/dummy_plugin/webhook_callbacks.py new file mode 100644 index 0000000000..095f545b55 --- /dev/null +++ b/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, + } diff --git a/netbox/netbox/tests/test_plugins.py b/netbox/netbox/tests/test_plugins.py index 9f2033936c..550dca514e 100644 --- a/netbox/netbox/tests/test_plugins.py +++ b/netbox/netbox/tests/test_plugins.py @@ -10,6 +10,7 @@ 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 @@ def test_events_pipeline(self): 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'])