WIP: Add event stream message format

Adds the structure of event stream messages using the OpenAPI `webhooks`
feature, a partial implementation of ADR0014 Option 2.

sem-ver: feature

README.md

@@ -133,6 +133,14 @@ In the diagram below, portions of Flow X and Flow Y are combined to form Flow Z,
 
 ![Graphic showing the Flow timeline and Flow Segments of Flows X, Y and Z, where Z is composed of a mix of re-used segments and new media](./docs/images/Flow%20and%20Media%20Timelines-Flow%20XYZ.drawio.png)
 
+### Events from the API
+
+The TAMS API specifies a list of event messages that should be generated and sent to interested clients in response to certain events, such as the creation of a new Flow.
+This is intended to reduce the amount of polling required by clients to keep up with activity on a store by providing a way to push updates about content they have access to instead.
+
+However the specification is deliberately left open-ended; only the message bodies are specified, but not the protocol by which they are carried nor the method by which clients subscribe.
+It is assumed that implementations will provide a suitable mechanism, such as a call to allow clients to subscribe to webhooks, or details of an event bus to connect to and receive the messages.
+
 ### API Versioning
 
 The API is versioned using a major and minor version number.

api/TimeAddressableMediaStore.yaml

@@ -1152,6 +1152,177 @@ paths:
                 $ref: schemas/deletion-request.json
               example:
                 $ref: examples/deletion-request-get-200.json
+
+webhooks:
+  flow/created:
+    post:
+      security:
+        - {}
+      requestBody:
+        content:
+          application/json:
+            schema:
+              title: Flow Created Notification
+              description: Information about a Flow which has been newly created in this store instance
+              required:
+                - event_timestamp
+                - event_type
+                - flow
+              properties:
+                event_timestamp:
+                  description: Timestamp at which the new Flow was created
+                  type: string
+                  format: date-time
+                event_type:
+                  type: string
+                  const: flow/created
+                flow:
+                  $ref: "schemas/flow-core.json"
+
+  flow/updated:
+    post:
+      security:
+        - {}
+      requestBody:
+        content:
+          application/json:
+            schema:
+              title: Flow Updated Notification
+              description: Information about a Flow for which the metadata has been modified.
+              required:
+                - event_timestamp
+                - event_type
+                - flow
+              properties:
+                event_timestamp:
+                  description: Timestamp at which the Flow was modified
+                  type: string
+                  format: date-time
+                event_type:
+                  type: string
+                  const: flow/updated
+                flow:
+                  $ref: "schemas/flow-core.json"
+
+  flow/deleted:
+    post:
+      security:
+        - {}
+      requestBody:
+        content:
+          application/json:
+            schema:
+              title: Flow Deleted Notification
+              description: Notification that a Flow has been deleted (or scheduled for deletion).
+              required:
+                - event_timestamp
+                - event_type
+                - flow_id
+              properties:
+                event_timestamp:
+                  description: Timestamp at which the Flow was modified
+                  type: string
+                  format: date-time
+                event_type:
+                  type: string
+                  const: flow/deleted
+                flow_id:
+                  $ref: "#/components/schemas/uuid"
+
+  flow/segments_added:
+    post:
+      security:
+        - {}
+      requestBody:
+        content:
+          application/json:
+            schema:
+              title: Flow Segments Added
+              description: |
+                Notification that new segments have been added to a Flow. The message body contains the timerange
+                covered by the new segments, however implementations MAY rate limit these messages and provide a single
+                message covering multiple segments. The timerange in the message MUST intersect with a segment at both
+                start and end (e.g. it cannot start or end in empty space).
+              required:
+                - event_timestamp
+                - event_type
+                - flow_id
+                - timerange
+              properties:
+                event_timestamp:
+                  description: Timestamp at which the most recent segment in the timerange was added (and the message generated)
+                  type: string
+                  format: date-time
+                event_type:
+                  type: string
+                  const: flow/segments_added
+                flow_id:
+                  $ref: "#/components/schemas/uuid"
+                timerange:
+                  $ref: 'schemas/timerange.json'
+
+  flow/segments_deleted:
+    post:
+      security:
+        - {}
+      requestBody:
+        content:
+          application/json:
+            schema:
+              title: Flow Segments Deleted
+              description: |
+                Notification that segments have been deleted from a Flow. The message body contains the timerange over
+                which segments have been deleted, however implementations MAY rate limit these messages and provide a
+                single message covering multiple segments. The timerange in the message MUST intersect with a segment
+                which has been deleted at both start and end (e.g. it cannot start or end in empty space).
+              required:
+                - event_timestamp
+                - event_type
+                - flow_id
+                - timerange
+              properties:
+                event_timestamp:
+                  description: Timestamp at which the most recent segment in the timerange was added (and the message generated)
+                  type: string
+                  format: date-time
+                event_type:
+                  type: string
+                  const: flow/segments_added
+                flow_id:
+                  $ref: "#/components/schemas/uuid"
+                timerange:
+                  $ref: 'schemas/timerange.json'
+
+  # TODO: Should Sources get created/deleted events too? If creation and deletion is a side effect of the same operation
+  # on Flows then it's strictly un-necessary, but if you're a client that only really deals in Sources, maybe you'd
+  # want that too?
+
+  source/updated:
+    post:
+      security:
+        - {}
+      requestBody:
+        content:
+          application/json:
+            schema:
+              title: Source Updated Notification
+              description: Information about a Source for which the metadata has been modified.
+              required:
+                - event_timestamp
+                - event_type
+                - source
+              properties:
+                event_timestamp:
+                  description: Timestamp at which the Source was modified
+                  type: string
+                  format: date-time
+                event_type:
+                  type: string
+                  const: source/updated
+                flow:
+                  $ref: "schemas/source.json"
+
+
 components:
   schemas:
     uuid: