Merge pull request #408 from apivideo/add-new-webhooks

Add new webhooks

oas_apivideo.yaml

@@ -14362,10 +14362,12 @@ paths:
       summary: Create Webhook
       description: |-
         Webhooks can push notifications to your server, rather than polling api.video for changes. We currently offer four events: 
-        * ```video.encoding.quality.completed``` Occurs when a new video is uploaded into your account, it will be encoded into several different HLS and mp4 qualities. When each version is encoded, your webhook will get a notification.  It will look like ```{ "type": "video.encoding.quality.completed", "emittedAt": "2021-01-29T16:46:25.217+01:00", "videoId": "viXXXXXXXX", "encoding": "hls", "quality": "720p"} ```. This request says that the 720p HLS encoding was completed.
-        * ```live-stream.broadcast.started```  When a live stream begins broadcasting, the broadcasting parameter changes from false to true, and this webhook fires.
-        * ```live-stream.broadcast.ended```  This event fires when a live stream has finished broadcasting.
-        * ```video.source.recorded```  This event occurs when a live stream is recorded and submitted for encoding.
+        * `video.encoding.quality.completed` Occurs when a new video is uploaded into your account, it will be encoded into several different HLS and mp4 qualities. When each version is encoded, your webhook will get a notification.  It will look like ```{ "type": "video.encoding.quality.completed", "emittedAt": "2021-01-29T16:46:25.217+01:00", "videoId": "viXXXXXXXX", "encoding": "hls", "quality": "720p"} ```. This request says that the 720p HLS encoding was completed.
+        * `live-stream.broadcast.started`  When a live stream begins broadcasting, the broadcasting parameter changes from false to true, and this webhook fires.
+        * `live-stream.broadcast.ended`  This event fires when a live stream has finished broadcasting.
+        * `video.source.recorded`  This event occurs when a live stream is recorded and submitted for encoding.
+        * `video.caption.generated`  This event occurs when an automatic caption has been generated.
+        * `video.summary.generated`  This event occurs when an automatic summary has been generated.
       operationId: POST-webhooks
       requestBody:
         required: true
@@ -15785,6 +15787,7 @@ components:
           example: '["video.encoding.quality.completed"]'
           items:
             type: string
+            enum: ['live-stream.broadcast.started', 'live-stream.broadcast.ended', 'video.source.recorded', 'video.encoding.quality.completed', 'video.caption.generated', 'video.summary.generated']
         url:
           type: string
           description: The URL where the API sends the webhook.
@@ -16885,15 +16888,12 @@ components:
         events:
           type: array
           description: |-
-            A list of the webhooks that you are subscribing to. There are Currently four webhook options:
-            * ```video.encoding.quality.completed```  Occurs when a new video is uploaded into your account, it will be encoded into several different HLS and mp4 qualities. When each version is encoded, your webhook will get a notification.  It will look like ```{ \"type\": \"video.encoding.quality.completed\", \"emittedAt\": \"2021-01-29T16:46:25.217+01:00\", \"videoId\": \"viXXXXXXXX\", \"encoding\": \"hls\", \"quality\": \"720p\"} ```. This request says that the 720p HLS encoding was completed.
-            * ```live-stream.broadcast.started```  When a live stream begins broadcasting, the broadcasting parameter changes from false to true, and this webhook fires.
-            * ```live-stream.broadcast.ended```  This event fires when a live stream has finished broadcasting.
-            * ```video.source.recorded```  Occurs when a live stream is recorded and submitted for encoding.
+            An array of webhook events that you want to subscribe to.
           example:
             - video.encoding.quality.completed
           items:
             type: string
+            enum: ['live-stream.broadcast.started', 'live-stream.broadcast.ended', 'video.source.recorded', 'video.encoding.quality.completed', 'video.caption.generated', 'video.summary.generated']
         url:
           type: string
           description: The the url to which HTTP notifications are sent. It could be any http or https URL.
@@ -17458,6 +17458,110 @@ x-webhooks:
                   type: string
                   enum: [240p, 360p, 480p, 720p, 1080p]
                   example: 1080p
+      responses:
+        '202':
+          summary: Accepted
+          description: Your webhook server may return this response to api.video to signal that the webhook is accepted.
+  video.caption.generated:
+    post:
+      tags:
+        - Webhooks
+      summary: Video caption generated
+      description: This webhook triggers when the API finishes generating a caption for a video.
+      operationId: POST-webhooks
+      parameters:
+        - in: header
+          name: X-Api-Video-WebhookID
+          schema:
+            type: string
+          description: The unique ID of your webhook.
+          required: true
+        - in: header
+          name: X-Api-Video-Signature
+          schema:
+            type: string
+          description: The webhook's body encrypted using the webhook's signature secret, in HMAC SHA256. Use this hash to verify that api.video is the origin of this webhook notification.
+          required: true
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                type:
+                  type: string
+                  description: The name of the webhook event that occurred.
+                  example: video.caption.generated
+                emittedAt:
+                  description: Returns the date-time when the webhook event occurred.
+                  type: string
+                  format: date-time
+                  example: '2024-08-151T10:18:47+00:00'
+                videoId:
+                  description: The ID of the video for which the caption was generated.
+                  type: string
+                  example: vi4blUQJFrYWbaG44NCh1234
+                captionId:
+                  description: The ID of the caption that was generated.
+                  type: string
+                  example: caption_1CHAfLFHT5B5EV4vzT1234
+                generationMode:
+                  description: Returns the method used to generate the caption. `transcript` means that the caption was generated based on the transcription of the video. Learn more about transcripts [here](https://docs.api.video/vod/generate-transcripts).
+                  type: string
+                  enum: [transcript]
+                  example: transcript
+                language:
+                  description: Returns the language of the captions in [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format.
+                  example: en
+                  type: string
+                  enum: [ar, ca, cs, da, de, el, en, es, fa, fi, fr, he, hi, hr, hu, it, ja, ko, ml, nl, nn, no, pl, pt, ru, sk, sl, te, tr, uk, ur, vi, zh]
+      responses:
+        '202':
+          summary: Accepted
+          description: Your webhook server may return this response to api.video to signal that the webhook is accepted.
+  video.summary.generated:
+    post:
+      tags:
+        - Webhooks
+      summary: Video summary generated
+      description: This webhook triggers when the API finishes generating a summary for a video.
+      operationId: POST-webhooks
+      parameters:
+        - in: header
+          name: X-Api-Video-WebhookID
+          schema:
+            type: string
+          description: The unique ID of your webhook.
+          required: true
+        - in: header
+          name: X-Api-Video-Signature
+          schema:
+            type: string
+          description: The webhook's body encrypted using the webhook's signature secret, in HMAC SHA256. Use this hash to verify that api.video is the origin of this webhook notification.
+          required: true
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                type:
+                  type: string
+                  description: The name of the webhook event that occurred.
+                  example: video.caption.generated
+                emittedAt:
+                  description: Returns the date-time when the webhook event occurred.
+                  type: string
+                  format: date-time
+                  example: '2024-08-151T10:18:47+00:00'
+                videoId:
+                  description: The ID of the video for which the summary was generated.
+                  type: string
+                  example: vi4blUQJFrYWbaG44NCh1234
+                summaryId:
+                  description: The ID of the summary that was generated.
+                  type: string
+                  example: summary_1CGyYoB9XCgBk4iQna8ocT
       responses:
         '202':
           summary: Accepted

templates/java/statics/android/src/androidTest/java/video/api/integration/WebhooksTest.java

@@ -45,7 +45,7 @@ public WebhooksTest() throws IOException {
     public void createWebhook() throws ApiException {
         this.webhook = apiClient.webhooks()
                 .create(new WebhooksCreationPayload()
-                        .events(Collections.singletonList("video.encoding.quality.completed"))
+                        .events(Collections.singletonList(WebhooksCreationPayload.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED))
                         .url("https://webhooks.test-java-api-client.fr"));
 
         assertThat(webhook.getWebhookId()).isNotNull();

templates/java/statics/android/src/test/java/video/api/client/api/clients/WebhooksApiTest.java

@@ -96,7 +96,7 @@ public void responseWithStatus200Test() throws ApiException {
 
             assertThat(res.getWebhookId()).isEqualTo("webhook_XXXXXXXXXXXXXXX");
             assertThat(res.getCreatedAt().toString()).isEqualTo("2021-01-08T14:12:18Z");
-            assertThat(res.getEvents()).containsExactlyElementsIn(Arrays.asList(("video.encoding.quality.completed")));
+            assertThat(res.getEvents()).containsExactlyElementsIn(Arrays.asList((Webhook.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED)));
             assertThat(res.getUrl()).isEqualTo("http://clientnotificationserver.com/notif?myquery=query");
         }
     }
@@ -131,12 +131,12 @@ public void responseWithStatus200Test() throws ApiException {
             assertThat(page.getItems()).containsExactlyElementsIn(Arrays.asList(
                     new Webhook().webhookId("webhook_XXXXXXXXXXXXXXX")
                             .createdAt(OffsetDateTime.parse("2021-01-08T14:12:18.000+00:00"))
-                            .addEventsItem("video.encoding.quality.completed")
+                            .addEventsItem(Webhook.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED)
                             .url("http://clientnotificationserver.com/notif?myquery=query")
                             .signatureSecret("sig_sec_Abcd12348RLP7VPLi7nYVh"),
                     new Webhook().webhookId("webhook_XXXXXXXXXYYYYYY")
                             .createdAt(OffsetDateTime.parse("2021-01-12T12:12:12.000+00:00"))
-                            .addEventsItem("video.encoding.quality.completed")
+                            .addEventsItem(Webhook.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED)
                             .url("http://clientnotificationserver.com/notif?myquery=query2")
                             .signatureSecret("sig_sec_Abcd12358RLP7VPLi7nYVy")))
                     .inOrder();

templates/java/statics/java/src/test/java/video/api/client/api/clients/WebhooksApiTest.java

@@ -93,7 +93,7 @@ public void responseWithStatus200Test() throws ApiException {
 
             assertThat(res.getWebhookId()).isEqualTo("webhook_XXXXXXXXXXXXXXX");
             assertThat(res.getCreatedAt()).isEqualTo("2021-01-08T14:12:18.000+00:00");
-            assertThat(res.getEvents()).containsExactlyInAnyOrder("video.encoding.quality.completed");
+            assertThat(res.getEvents()).containsExactlyInAnyOrder(Webhook.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED);
             assertThat(res.getUrl()).isEqualTo("http://clientnotificationserver.com/notif?myquery=query");
         }
     }
@@ -128,12 +128,12 @@ public void responseWithStatus200Test() throws ApiException {
             assertThat(page.getItems()).containsExactlyInAnyOrder(
                     new Webhook().webhookId("webhook_XXXXXXXXXXXXXXX")
                             .createdAt(OffsetDateTime.parse("2021-01-08T14:12:18.000+00:00"))
-                            .addEventsItem("video.encoding.quality.completed")
+                            .addEventsItem(Webhook.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED)
                             .url("http://clientnotificationserver.com/notif?myquery=query")
                             .signatureSecret("sig_sec_Abcd12348RLP7VPLi7nYVh"),
                     new Webhook().webhookId("webhook_XXXXXXXXXYYYYYY")
                             .createdAt(OffsetDateTime.parse("2021-01-12T12:12:12.000+00:00"))
-                            .addEventsItem("video.encoding.quality.completed")
+                            .addEventsItem(Webhook.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED)
                             .url("http://clientnotificationserver.com/notif?myquery=query2")
                             .signatureSecret("sig_sec_Abcd12358RLP7VPLi7nYVy"));
         }

templates/java/statics/java/src/test/java/video/api/integration/WebhooksTest.java

@@ -27,7 +27,7 @@ public class WebhooksTest extends AbstractTest {
     public void createWebhook() throws ApiException {
         this.webhook = apiClient.webhooks()
                 .create(new WebhooksCreationPayload()
-                        .events(Collections.singletonList("video.encoding.quality.completed"))
+                        .events(Collections.singletonList(WebhooksCreationPayload.EventsEnum.VIDEO_ENCODING_QUALITY_COMPLETED))
                         .url("https://webhooks.test-java-api-client.fr"));
 
         assertThat(webhook.getWebhookId()).isNotNull();