Change `id` in the push gateway poke to be `event_id` and spec that it's the Matrix event ID of the message. Correct the spec for badge count pushes which omit fields previously described as mandatory. Add more detail about when to use event_id to suppress dupes. Also add the push gateway doc so it's actually included in the spec.

api/push-gateway/push_notifier.yaml

@@ -17,7 +17,17 @@ paths:
       summary: Notify a push gateway about an event.
       description: |-
         This endpoint is invoked by HTTP pushers to notify a push gateway about
-        an event.
+        an event or update the number of unread notifications a user has.
+        In the former case it will contain selected information about the event.
+        In either case it may contain numeric counts of the number of unread
+        events of different types the user has. The counts may be sent along
+        with a notification about an event or by themselves.
+        Notifications about a particular event will normally cause the user to be
+        alerted in some way. It is therefore necessary to perform duplicate
+        suppression for such notifications using the `event_id` field to avoid
+        retries of this HTTP API causing duplicate alerts. The operation of
+	updating counts of unread notifications should be and therefore do not
+        require duplicate suppression.
         *NB: Notifications are sent to the URL configured when the pusher is
         created. This means that the HTTP path may be different depending on the
         push gateway.*
@@ -65,24 +75,34 @@ paths:
               notification:
                 type: object
                 description: Information about the push notification
-                required: ["id", "room_id", "type", "sender"]
+                required: []
                 properties:
-                  id:
+                  event_id:
                     type: string
                     description: |-
-                      An identifier for this notification that may be used to
-                      detect duplicate notification requests. This is not
-                      necessarily the ID of the event that triggered the
-                      notification.
+                      The Matrix event ID of the event being notified about.
+                      This is required if the notification is about a
+                      particular Matrix event. It may be omitted for notifications
+                      that only contain updated badge counts. This ID can and
+                      should be used to detect duplicate notification requests.
                   room_id:
                     type: string
-                    description: The ID of the room in which this event occurred.
+                    description: |-
+                      The ID of the room in which this event occurred.
+                      Required if the notification relates to a specific
+                      Matrix event.
                   type:
                     type: string
-                    description: The type of the event as in the event's ``type`` field.
+                    description: |-
+                      The type of the event as in the event's ``type`` field.
+                      Required if the notification relates to a specific
+                      Matrix event.
                   sender:
                     type: string
-                    description: The sender of the event as in the corresponding event field.
+                    description: |-
+                      The sender of the event as in the corresponding event field.
+                      Required if the notification relates to a specific
+                      Matrix event.
                   sender_display_name:
                     type: string
                     description: |-

specification/index.rst

@@ -20,6 +20,7 @@ The following APIs are documented in this specification:
 - `Server-Server API <server_server.html>`_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix.
 - `Application Service API <application_service.html>`_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers.
 - `Identity Service API <identity_service.html>`_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs.
+- `Push Gateway API <push_gateway.html>`_ version unstable for implementing a server that receives notifications about Matrix events a user is interested in.
 
 There are also some `appendices <appendices.html>`_.
 

specification/push_gateway.rst

@@ -39,4 +39,4 @@ This describes the format used by "HTTP" pushers to send notifications of
 events to Push Gateways. If the endpoint returns an HTTP error code, the
 homeserver SHOULD retry for a reasonable amount of time using exponential backoff.
 
-{{push_notifier_http_api}}
+{{push_notifier_push_http_api}}

specification/targets.yaml

@@ -22,6 +22,9 @@ targets:
   identity_service:
     files:
       - identity_service_api.rst
+  push_gateway:
+    files:
+      - push_gateway.rst
   appendices:
     files:
       - appendices.rst

templating/matrix_templates/units.py

@@ -21,6 +21,7 @@ HTTP_APIS = {
     "../api/application-service": "as",
     "../api/client-server": "cs",
     "../api/identity": "is",
+    "../api/push-gateway": "push",
 }
 EVENT_EXAMPLES = "../event-schemas/examples"
 EVENT_SCHEMA = "../event-schemas/schema"