Improvements to webhooks endpoints

api/TimeAddressableMediaStore.yaml

@@ -153,9 +153,29 @@ paths:
       operationId: HEAD_webhooks
       tags:
         - Webhooks
+      parameters:
+        - $ref: '#/components/parameters/trait_resource_paged_key'
+        - $ref: '#/components/parameters/trait_paged_limit'
       responses:
         "200":
-          $ref: '#/components/responses/trait_resource_listing_head_200'
+          description: ""
+          headers:
+            Link:
+              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
+              schema:
+                type: string
+            X-Paging-Limit:
+              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
+              schema:
+                type: integer
+            X-Paging-NextKey:
+              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: string
         "404":
           description: "Webhooks are not supported by this service implementation"
     get:
@@ -167,33 +187,118 @@ paths:
       operationId: GET_webhooks
       tags:
         - Webhooks
+      parameters:
+        - $ref: '#/components/parameters/trait_resource_paged_key'
+        - $ref: '#/components/parameters/trait_paged_limit'
       responses:
         "200":
-          description: Return the list of known webhook URLs. Note that the `api_key_value` will be omitted.
+          description: Return the list of known webhook URLs.
+          headers:
+            Link:
+              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
+              schema:
+                type: string
+            X-Paging-Limit:
+              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
+              schema:
+                type: integer
+            X-Paging-NextKey:
+              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
+              schema:
+                type: string
           content:
             application/json:
               example:
-                - url: https://hook.example.com
-                  api_key_name: Authorization
-                  events:
-                    - flows/created
-                    - flows/updated
-                    - flows/deleted
+                $ref: "examples/webhook-get-200-list.json"
               schema:
                 type: array
                 items:
-                  $ref: "schemas/webhook.json"
+                  $ref: "schemas/webhook-get.json"
         "404":
-          description: "Webhooks are not supported by this service implementation"
+          description: "Webhooks are not supported by this API implementation"
     post:
-      summary: Register Webhook URL
+      summary: Register webhook details
       description: |
-        Register to receive event notifications as webhooks on a specified URL.
-        Webhook messages will conform to the format in the `webhooks` section of the API docs, depending on the event type (as defined in the same section).
-        Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms` list on the [/service](#/operations/GET_service) endpoint.
+        Register to receive event notifications as webhooks on a specified URL. Webhook messages will conform to the
+        format in the `webhooks` section of the API docs, depending on the event type (as defined in the same section).
+        Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms`
+        list on the service endpoint.
+
+        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.
 
-        Making a POST request to this endpoint with the same URL, API key name and value but a different list of `events` SHOULD update the existing registration.
-        POSTing an empty list of events SHOULD remove the registration.
+        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. API implementations SHOULD take appropriate steps to authorize the modification of existing webhooks. This may take the form of RBAC, or ABAC.
+      operationId: POST_webhooks
+      tags:
+        - Webhooks
+      requestBody:
+        content:
+          application/json:
+            example:
+              $ref: "examples/webhook-post.json"
+            schema:
+              $ref: schemas/webhook-post.json
+        required: true
+      responses:
+        "201":
+          description: Success. The webhook has been registered.
+          content:
+            application/json:
+              example:
+                $ref: "examples/webhook-get-200.json"
+              schema:
+                $ref: schemas/webhook-get.json
+        "400":
+          description: Bad request. Invalid parameters or unsupported event filtering or transformation.
+        "404":
+          description: Webhooks are not supported by this service implementation
+  /service/webhooks/{webhookId}:
+    parameters:
+      - name: webhookId
+        in: path
+        required: true
+        schema:
+          $ref: 'schemas/uuid.json'
+        description: The Webhook identifier.
+    head:
+      summary: Webhook details
+      description: Return webhook path headers
+      operationId: HEAD_webhooks-webhookId
+      tags:
+        - Webhooks
+      responses:
+        "200":
+          $ref: '#/components/responses/trait_resource_listing_head_200'
+        "404":
+          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation
+    get:
+      summary: Webhook details
+      description: |
+        Get the details of a webhook. Service implementations SHOULD take steps to avoid displaying URLs to users other than those who have suitable permissions (e.g. the owning user).
+        Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms` list on the [`/service`](#/operations/GET_service) endpoint.
+      operationId: GET_webhooks-webhookId
+      tags:
+        - Webhooks
+      responses:
+        "200":
+          description: Return the webhook details.
+          content:
+            application/json:
+              example:
+                $ref: "examples/webhook-get-200.json"
+              schema:
+                $ref: "schemas/webhook-get.json"
+        "404":
+          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation
+    put:
+      summary: Update webhook details
+      description: |
+        Update the configuration of an existing webhook.
+
+        Webhook messages will conform to the format in the `webhooks` section of the API docs, depending on the event type (as defined in the same section).
+        Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms` list on the [`/service`](#/operations/GET_service) endpoint.
 
         HTTP events sent by the service to a client webhook's endpoint 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.
@@ -202,33 +307,53 @@ paths:
         Service implementations SHALL return a 400 response code if the filtering or transformation specified in the request is not supported.
 
         Service implementations SHOULD consider the security implications of providing webhooks, and include appropriate mitigations against Server Side Request Forgery (SSRF) attacks and similar.
-      operationId: POST_webhooks
+        Service implementations SHOULD take appropriate steps to authorize the modification of existing webhooks. 
+        This may take the form of RBAC, or ABAC.
+      operationId: PUT_webhooks
       tags:
         - Webhooks
       requestBody:
         content:
           application/json:
             example:
-              url: https://hook.example.com
-              api_key_name: Authorization
-              api_key_value: Bearer 21238dksdjqwpqscj9
-              events:
-                - flows/created
-                - flows/updated
+              $ref: "examples/webhook-put.json"
             schema:
-              $ref: schemas/webhook-post.json
+              $ref: schemas/webhook-put.json
         required: true
       responses:
         "201":
-          description: Success. The webhook has been registered or updated
-        "204":
-          description: Success. The webhook has been removed
+          description: Success. The webhook has been updated
+          content:
+            application/json:
+              example:
+                $ref: "examples/webhook-get-200.json"
+              schema:
+                $ref: schemas/webhook-get.json
         "400":
           description: Bad request. Invalid parameters or unsupported event filtering or transformation.
         "403":
           description: Forbidden. You do not have permission to modify this resource.
         "404":
-          description: "Webhooks are not supported by this service implementation"
+          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation
+    delete:
+      summary: Delete Webhook
+      description: |
+        Deletes the webhook. 
+        Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms` list on the service endpoint.
+
+        Service implementations SHOULD consider the security implementations of providing webhooks, and include appropriate mitigations against Server Side Request Forgery (SSRF) attacks and similar. 
+        Service implementations SHOULD take appropriate steps to authorize the deleting of webhooks. 
+        This may take the form of RBAC, or ABAC.
+      operationId: DELETE_webhooks-webhookId
+      tags:
+        - Webhooks
+      responses:
+        "204":
+          description: No content. The webhook has been deleted.
+        "403":
+          description: Forbidden. You do not have permission to modify this webhook.
+        "404":
+          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation
   /sources:
     head:
       summary: List Sources
@@ -2445,7 +2570,7 @@ webhooks:
                   format: date-time
                 event_type:
                   type: string
-                  const: flows/segments_added
+                  const: flows/segments_deleted
                 event:
                   type: object
                   required:

api/examples/webhook-get-200-list.json

@@ -0,0 +1,12 @@
+[
+    {
+        "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
+        "url": "https://hook.example.com",
+        "api_key_name": "Authorization",
+        "events": [
+            "flows/created",
+            "flows/updated"
+        ],
+        "status": "started"
+    }
+]

api/examples/webhook-get-200.json

@@ -0,0 +1,10 @@
+{
+    "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
+    "url": "https://hook.example.com",
+    "api_key_name": "Authorization",
+    "events": [
+        "flows/created",
+        "flows/updated"
+    ],
+    "status": "started"
+}

api/examples/webhook-post.json

@@ -0,0 +1,9 @@
+{
+    "url": "https://hook.example.com",
+    "api_key_name": "Authorization",
+    "api_key_value": "Bearer 21238dksdjqwpqscj9",
+    "events": [
+        "flows/created",
+        "flows/updated"
+    ]
+}

api/examples/webhook-put.json

@@ -0,0 +1,11 @@
+{
+    "id": "e85efab4-993b-4ad6-9af3-4cd8d0d38860",
+    "url": "https://hook.example.com",
+    "api_key_name": "Authorization",
+    "api_key_value": "Bearer 21238dksdjqwpqscj9",
+    "events": [
+        "flows/created",
+        "flows/updated"
+    ],
+    "status": "created"
+}

api/schemas/webhook-get.json

@@ -0,0 +1,33 @@
+{
+    "title": "Webhook Detail",
+    "description": "Describes a Webhook",
+    "type": "object",
+    "allOf": [
+        {
+            "$ref": "webhook-with-id.json"
+        },
+        {
+            "type": "object",
+            "required":
+            [
+                "status"
+            ],
+            "properties": {
+                "error": {
+                    "description": "Provides more information for the error status, as described by the [Error](../schemas/error#top) type",
+                    "$ref": "error.json"
+                },
+                "status": {
+                    "description": "Status of the Webhook. `created` indicates the webhook has been successfully registered but is yet to begin sending events or, depending on the service implementation, the worker responsible for sending the events has yet to start. `started` indicates the webhook is active and sending events. `disabled` indicates the webhook has been disabled by a client and is not currently sending events. `error` indicates an error condition has been encountered and the webhook has been disabled by the service instance. More information about the error condition will be indicated by the service instance in the `error` parameter. Service implementations SHOULD implement appropriate retries and only enter the `error` state when absolutely necesary. A webhook in the `error` or `disabled` state may be re-enabled by a client by setting the status to `created`. A webhook in the `created` or `started` state may be disabled by a client by setting the status to `disabled`. Attempting to transition an `error` status to `disabled` SHOULD be rejected.",
+                    "type": "string",
+                    "enum": [
+                        "created",
+                        "started",
+                        "disabled",
+                        "error"
+                    ]
+                }
+            }
+        }
+    ]
+}