Merge pull request #51 from bbc/philipn-modify-webhooks-api

Modify the webhooks api
bbc · May 2, 2024 · 9c77f44 · 9c77f44
2 parents 1048f78 + 8e531fb
commit 9c77f44
Show file tree

Hide file tree

Showing 4 changed files with 120 additions and 43 deletions.
diff --git a/api/TimeAddressableMediaStore.yaml b/api/TimeAddressableMediaStore.yaml
@@ -141,11 +141,12 @@ paths:
         - Webhooks
       responses:
         "200":
-          description: Return the list of known webhook URLs. Note that the `secret` will be omitted.
+          description: Return the list of known webhook URLs. Note that the `api_key_value` will be omitted.
           content:
             application/json:
               example:
                 - url: https://hook.example.com
+                  api_key_name: Authorization
                   events:
                     - flows/created
                     - flows/updated
@@ -165,12 +166,11 @@ paths:
         Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms`
         list on the service endpoint.
 
-        Making a POST request to this endpoint with the same URL and secret but a different list of `events` SHOULD
-        update the existing registration. POSTing an empty list of events SHOULD remove the registration.
+        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.
 
-        HTTP requests from the service SHOULD include a `X-Hook-Signature` header containing the HMAC hex digest of the
-        webhook body, hashed using SHA-256 using the shared secret as the key. Clients SHOULD verify each message using
-        the shared secret.
+        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 SHOULD consider the security implementations of providing webhooks, and include appropriate
         mitigations against Server Side Request Forgery (SSRF) attacks and similar.
@@ -182,16 +182,19 @@ paths:
           application/json:
             example:
               url: https://hook.example.com
-              secret: super-secret-string
+              api_key_name: Authorization
+              api_key_value: Bearer 21238dksdjqwpqscj9
               events:
                 - flows/created
                 - flows/updated
             schema:
-              $ref: schemas/webhook.json
+              $ref: schemas/webhook-post.json
         required: true
       responses:
-        "200":
-          description: Success. The webhook has been registered
+        "201":
+          description: Success. The webhook has been registered or updated
+        "204":
+          description: Success. The webhook has been removed
         "404":
           description: "Webhooks are not supported by this API implementation"
 
@@ -1304,7 +1307,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - flow
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the new Flow was created
@@ -1313,8 +1316,13 @@ webhooks:
                 event_type:
                   type: string
                   const: flows/created
-                flow:
-                  $ref: "schemas/flow-core.json"
+                event:
+                  type: object
+                  required:
+                    - flow
+                  properties:
+                    flow:
+                      $ref: "schemas/flow.json"
 
   flows/updated:
     post:
@@ -1329,7 +1337,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - flow
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the Flow was modified
@@ -1338,8 +1346,13 @@ webhooks:
                 event_type:
                   type: string
                   const: flows/updated
-                flow:
-                  $ref: "schemas/flow-core.json"
+                event:
+                  type: object
+                  required:
+                    - flow
+                  properties:
+                    flow:
+                      $ref: "schemas/flow.json"
 
   flows/deleted:
     post:
@@ -1354,7 +1367,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - flow_id
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the Flow was modified
@@ -1363,8 +1376,13 @@ webhooks:
                 event_type:
                   type: string
                   const: flows/deleted
-                flow_id:
-                  $ref: "#/components/schemas/uuid"
+                event:
+                  type: object
+                  required:
+                    - flow_id
+                  properties:
+                    flow_id:
+                      $ref: "#/components/schemas/uuid"
 
   flows/segments_added:
     post:
@@ -1383,8 +1401,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - flow_id
-                - timerange
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the most recent segment in the timerange was added (and the message generated)
@@ -1393,10 +1410,16 @@ webhooks:
                 event_type:
                   type: string
                   const: flows/segments_added
-                flow_id:
-                  $ref: "#/components/schemas/uuid"
-                timerange:
-                  $ref: 'schemas/timerange.json'
+                event:
+                  type: object
+                  required:
+                    - flow_id
+                    - timerange
+                  properties:
+                    flow_id:
+                      $ref: "#/components/schemas/uuid"
+                    timerange:
+                      $ref: 'schemas/timerange.json'
 
   flows/segments_deleted:
     post:
@@ -1415,8 +1438,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - flow_id
-                - timerange
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the most recent segment in the timerange was added (and the message generated)
@@ -1425,10 +1447,16 @@ webhooks:
                 event_type:
                   type: string
                   const: flows/segments_added
-                flow_id:
-                  $ref: "#/components/schemas/uuid"
-                timerange:
-                  $ref: 'schemas/timerange.json'
+                event:
+                  type: object
+                  required:
+                    - flow_id
+                    - timerange
+                  properties:
+                    flow_id:
+                      $ref: "#/components/schemas/uuid"
+                    timerange:
+                      $ref: 'schemas/timerange.json'
 
   sources/created:
     post:
@@ -1443,7 +1471,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - source
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the new Source was created
@@ -1452,8 +1480,13 @@ webhooks:
                 event_type:
                   type: string
                   const: sources/created
-                source:
-                  $ref: "schemas/source.json"
+                event:
+                  type: object
+                  required:
+                    - source
+                  properties:
+                    source:
+                      $ref: "schemas/source.json"
 
   sources/updated:
     post:
@@ -1468,7 +1501,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - source
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the Source was modified
@@ -1477,8 +1510,13 @@ webhooks:
                 event_type:
                   type: string
                   const: sources/updated
-                source:
-                  $ref: "schemas/source.json"
+                event:
+                  type: object
+                  required:
+                    - source
+                  properties:
+                    source:
+                      $ref: "schemas/source.json"
 
   sources/deleted:
     post:
@@ -1493,7 +1531,7 @@ webhooks:
               required:
                 - event_timestamp
                 - event_type
-                - source_id
+                - event
               properties:
                 event_timestamp:
                   description: Timestamp at which the Source was modified
@@ -1502,8 +1540,13 @@ webhooks:
                 event_type:
                   type: string
                   const: sources/deleted
-                source_id:
-                  $ref: "#/components/schemas/uuid"
+                event:
+                  type: object
+                  required:
+                    - source_id
+                  properties:
+                    source_id:
+                      $ref: "#/components/schemas/uuid"
 
 components:
   schemas:

diff --git a/api/examples/service-get-200.json b/api/examples/service-get-200.json
@@ -8,7 +8,7 @@
   },
   "event_stream_mechanisms": [
     {
-      "name": "webhook",
+      "name": "webhooks",
       "docs": "https://bbc.github.io/tams/#/operations/POST_webhooks"
     }
   ]

diff --git a/api/schemas/webhook-post.json b/api/schemas/webhook-post.json
@@ -0,0 +1,30 @@
+{
+    "title": "Register Webhook",
+    "description": "Register to receive updates via webhook",
+    "type": "object",
+    "required": [
+        "url",
+        "events"
+    ],
+    "properties": {
+        "url": {
+            "description": "The URL to which the API should make HTTP POST requests with event data",
+            "type": "string"
+        },
+        "api_key_name": {
+            "description": "The HTTP header name that is added to the event POST with value 'api_key_value'",
+            "type": "string"
+        },
+        "api_key_value": {
+            "description": "The value that the HTTP header 'api_key_name' will be set to",
+            "type": "string"
+        },
+        "events": {
+            "description": "List of event types to receive",
+            "type": "array",
+            "items": {
+                "type": "string"
+            }
+        }
+    }
+}
diff --git a/api/schemas/webhook.json b/api/schemas/webhook.json
@@ -11,8 +11,12 @@
             "description": "The URL to which the API should make HTTP POST requests with event data",
             "type": "string"
         },
-        "secret": {
-            "description": "A shared secret, used to sign deliveries to clients so they can validate the source",
+        "api_key_name": {
+            "description": "The HTTP header name that is added to the event POST",
+            "type": "string"
+        },
+        "api_key_value": {
+            "description": "The value that the HTTP header 'api_key_name' will be set to",
             "type": "string"
         },
         "events": {