Clarify that servers must forward custom keys in PusherData (#1973)

Relates to: #921
Signed-off-by: Johannes Marbach <[email protected]>

changelogs/client_server/newsfragments/1973.clarification

@@ -0,0 +1 @@
+Clarify that servers must forward custom keys in `PusherData` when sending notifications to the push gateway.

data/api/client-server/pusher.yaml

@@ -210,17 +210,21 @@ paths:
                   type: object
                   description: |-
                     Required if `kind` is not `null`. A dictionary of information
-                    for the pusher implementation itself. If `kind` is `http`,
-                    this should contain `url` which is the URL to use to send
-                    notifications to.
+                    for the pusher implementation itself.
+
+                    If `kind` is `http`, this MUST contain `url` which is the URL
+                    to use for sending notifications. Clients MAY use this object
+                    to pass custom data to their push gateway. Servers MUST forward
+                    the entire content including `format` and any custom keys but excluding `url`
+                    when calling [`/_matrix/push/v1/notify`](/push-gateway-api/#post_matrixpushv1notify).
                   title: PusherData
                   properties:
                     url:
                       type: string
                       format: uri
                       description: |-
-                        Required if `kind` is `http`. The URL to use to send
-                        notifications to. MUST be an HTTPS URL with a path of
+                        Required if `kind` is `http`. The URL to use for sending
+                        notifications. MUST be an HTTPS URL with a path of
                         `/_matrix/push/v1/notify`.
                       example: https://push-gateway.location.here/_matrix/push/v1/notify
                     format: