Updates to Webhook events and filtering

api/TimeAddressableMediaStore.yaml

@@ -175,6 +175,9 @@ paths:
 
         HTTP requests from the service SHOULD include a `api_key_name` header with the 'api_key_value' value. Clients SHOULD verify this against the value they provided when registering the webhook.
 
+        API implementations MAY partially support event filtering and transformations.
+        API implementations SHALL return a 400 response code if the filtering or transformation specified in the request is not supported.
+
         API implementations SHOULD consider the security implementations of providing webhooks, and include appropriate
         mitigations against Server Side Request Forgery (SSRF) attacks and similar.
       operationId: POST_webhooks
@@ -199,7 +202,7 @@ paths:
         "204":
           description: Success. The webhook has been removed
         "400":
-          description: Bad request. Invalid parameters.
+          description: Bad request. Invalid parameters or unsupported event filtering or transformation.
         "404":
           description: "Webhooks are not supported by this API implementation"
   /sources:
@@ -2001,10 +2004,7 @@ webhooks:
             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).
+                Notification that new segments have been added to a Flow.
               required:
                 - event_timestamp
                 - event_type
@@ -2021,12 +2021,14 @@ webhooks:
                   type: object
                   required:
                     - flow_id
-                    - timerange
+                    - segments
                   properties:
                     flow_id:
                       $ref: "#/components/schemas/uuid"
-                    timerange:
-                      $ref: 'schemas/timerange.json'
+                    segments:
+                      type: array
+                      items:
+                        $ref: 'schemas/flow-segment.json'
   flows/segments_deleted:
     post:
       security:
@@ -2037,10 +2039,7 @@ webhooks:
             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).
+                Notification that segments have been deleted from a Flow.
               required:
                 - event_timestamp
                 - event_type
@@ -2062,6 +2061,7 @@ webhooks:
                     flow_id:
                       $ref: "#/components/schemas/uuid"
                     timerange:
+                      description: The timerange of segments that have been deleted. The timerange MUST intersect with a segment which has been deleted at both start and end (e.g. it cannot start or end in empty space).
                       $ref: 'schemas/timerange.json'
   sources/created:
     post:

api/schemas/webhook-post.json

@@ -27,20 +27,43 @@
             }
         },
         "flow_ids": {
-            "description": "Limit Flow related events to the given list of Flow IDs. Non-Flow related events are not affected",
+            "description": "Limit Flow and Flow Segment events to Flows in the given list of Flow IDs",
             "type": "array",
             "items": {
                 "type": "string",
                 "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
             }
         },
         "source_ids": {
-            "description": "Limit Source related events to the given list of Source IDs. Non-Source related events are not affected",
+            "description": "Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs",
             "type": "array",
             "items": {
                 "type": "string",
                 "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
             }
+        },
+        "flow_collected_by_ids": {
+            "description": "Limit Flow and Flow Segment events to those with Flow that is collected by a Flow Collection in the given list of Flow Collection IDs",
+            "type": "array",
+            "items": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+            }
+        },
+        "source_collected_by_ids": {
+            "description": "Limit Flow, Flow Segment and Source events to those with Source that is collected by a Source Collection in the given list of Source Collection IDs",
+            "type": "array",
+            "items": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+            }
+        },
+        "accept_get_urls": {
+            "description": "List of labels of URLs to include in the `get_urls` property in `flows/segments_added` events. This option is the same as the `accept_get_urls` query parameter for the /flows/{flowId}/segments API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string.",
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
         }
     }
 }

api/schemas/webhook.json

@@ -27,20 +27,43 @@
             }
         },
         "flow_ids": {
-            "description": "Limit Flow related events to the given list of Flow IDs. Non-Flow related events are not affected",
+            "description": "Limit Flow and Flow Segment events to Flows in the given list of Flow IDs",
             "type": "array",
             "items": {
                 "type": "string",
                 "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
             }
         },
         "source_ids": {
-            "description": "Limit Source related events to the given list of Source IDs. Non-Source related events are not affected",
+            "description": "Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs",
             "type": "array",
             "items": {
                 "type": "string",
                 "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
             }
+        },
+        "flow_collected_by_ids": {
+            "description": "Limit Flow and Flow Segment events to those with Flow that is collected by a Flow Collection in the given list of Flow Collection IDs",
+            "type": "array",
+            "items": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+            }
+        },
+        "source_collected_by_ids": {
+            "description": "Limit Flow, Flow Segment and Source events to those with Source that is collected by a Source Collection in the given list of Source Collection IDs",
+            "type": "array",
+            "items": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+            }
+        },
+        "accept_get_urls": {
+            "description": "List of labels of URLs to include in the `get_urls` property in `flows/segments_added` events. This option is the same as the `accept_get_urls` query parameter for the /flows/{flowId}/segments API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string.",
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
         }
     }
 }

docs/README.md

@@ -35,6 +35,7 @@ For more information on how we use ADRs, see [here](./adr/README.md).
 | [0023](./adr/0023-filter-segment-get-urls.md)                      | Add query option to filter Flow Segment `get_urls` by `label`              |
 | [0024](./adr/0024-source-level-edit.md)                            | Source-level Edit                                                          |
 | [0025](./adr/0025-flow-property-updates.md)                        | Options for updating Flow properties                                       |
+| [0026](./adr/0026-updated-webhook-events-and-filters.md)           | Updates to the webhook event structures and filters                        |
 
 \* Note: ADR 0004a was the unintended result of a number clash in the early development of TAMS which wasn't caught before publication