Add documentation for OpenApiWebhook

drf_spectacular/settings.py

@@ -199,7 +199,8 @@
     'SERVERS': [],
     # Tags defined in the global scope
     'TAGS': [],
-    # Optional: List of OpenAPI 3.1 webhooks.
+    # Optional: List of OpenAPI 3.1 webhooks. Each entry should be an import path to an
+    # OpenApiWebhook instance.
     'WEBHOOKS': None,
     # Optional: MUST contain 'url', may contain "description"
     'EXTERNAL_DOCS': {},

drf_spectacular/utils.py

@@ -317,6 +317,23 @@ def __init__(
 
 
 class OpenApiWebhook(OpenApiSchemaBase):
+    """
+    Helper class to document webhook definitions. A webhook specifies a possible out-of-band
+    request initiated by the API provider and the expected responses from the consumer.
+
+    Please note that this particular :func:`@extend_schema <.extend_schema>` instance operates
+    from the perspective of the webhook origin, which means that ``request`` specifies the
+    outgoing request.
+
+    For convenience sake, we assume the API provider sends a POST request with a body of type
+    ``application/json`` and the receiver responds with ``200`` if the event was successfully
+    received.
+
+    :param name: Name under which this webhook is listed in the schema.
+    :param decorator: :func:`@extend_schema <.extend_schema>` decorator that specifies the receiving
+        endpoint. In this special context the allowed parameters are ``requests``, ``responses``,
+        ``summary``, ``description``, ``deprecated``.
+    """
     def __init__(
             self,
             name: _StrOrPromise,

tests/test_webhooks.py

@@ -20,7 +20,7 @@ class EventSerializer(serializers.Serializer):
     name='SubscriptionEvent',
     decorator=extend_schema(
         summary="some summary",
-        description='pushes events to callbackUrl as "application/x-www-form-urlencoded"',
+        description='pushes events to a webhook url as "application/x-www-form-urlencoded"',
         request={
             'application/x-www-form-urlencoded': EventSerializer,
         },

tests/test_webhooks.yml

@@ -23,7 +23,7 @@ components:
 webhooks:
   SubscriptionEvent:
     post:
-      description: pushes events to callbackUrl as "application/x-www-form-urlencoded"
+      description: pushes events to a webhook url as "application/x-www-form-urlencoded"
       summary: some summary
       requestBody:
         content: