neoris/openvidu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backend: Standardize webhook parameter names and descriptions; implement schemas for webhook events

Browse Source
This commit is contained in:
Carlos Santos 2025-05-05 18:24:29 +02:00
parent bbbb7fc0c1
commit b613bcb53d
6 changed files with 192 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
backend/openapi/components/parameters/x-signature.yaml
View File

@ -1,5 +1,9 @@
name: X-Signature name: x-signature
in: header in: header
description: HMAC signature for webhook verification. description: >
HMAC-SHA256 signature of the request body, created using your webhook secret.
Use this to verify the webhook came from OpenVidu Meet and wasn't tampered with.
required: true
schema: schema:
type: string type: string

8
backend/openapi/components/parameters/x-timestamp.yaml
View File

@ -1,6 +1,10 @@
name: X-Timestamp name: x-timestamp
in: header in: header
description: Timestamp of the webhook event (in Unix Epoch milliseconds). description: >
Unix timestamp (in seconds) when the webhook was sent.
Can be used to validate webhook age and prevent replay attacks.
required: true
schema: schema:
type: string type: string
example: '1697030400000' example: '1697030400000'

7
backend/openapi/components/responses/webhook-success.yaml Normal file
View File

@ -0,0 +1,7 @@
description: >
Webhook received and processed successfully.
Important: Webhook endpoints must return HTTP 200 OK promptly to acknowledge receipt.
Any processing should be done asynchronously after responding.
Non-200 responses or timeouts will trigger retries according to the webhook delivery policy.

23
backend/openapi/components/schemas/recording-base.yaml Normal file
View File

@ -0,0 +1,23 @@
type: object
required:
- recordingId
- roomId
- filename
- startDate
properties:
recordingId:
type: string
description: The unique identifier of the recording.
example: room-123--EG_XYZ--XX445
roomId:
type: string
description: The ID of the room where the recording was made.
example: room-123
filename:
type: string
description: The name of the recording file.
example: room-123--XX445.mp4
startDate:
type: number
description: The date when the recording started (milliseconds since the Unix epoch).
example: 1620000000000

17
backend/openapi/components/schemas/webhook-base-event.yaml Normal file
View File

@ -0,0 +1,17 @@
type: object
required:
- creationDate
- event
- data
properties:
creationDate:
type: number
description: The date when the event was created (milliseconds since the Unix epoch).
example: 1620000000000
event:
type: string
description: Event type identifier.
example: webhookEvent
data:
type: object
description: The data associated with the event.

173
backend/openapi/webhooks/webhooks.yaml
View File

@ -5,51 +5,39 @@ recordingStarted:
This webhook is triggered when a recording starts. This webhook is triggered when a recording starts.
> The recording can be in the `STARTING` status for a few seconds before it becomes `ACTIVE`. > The recording can be in the `STARTING` status for a few seconds before it becomes `ACTIVE`.
operationId: recordingStartedWebhook operationId: recordingStartedWebhook
parameters: parameters:
- $ref: ../components/parameters/x-timestamp.yaml - $ref: ../components/parameters/x-timestamp.yaml
- $ref: ../components/parameters/x-signature.yaml - $ref: ../components/parameters/x-signature.yaml
# TODO: Use defined schema for request body
requestBody: requestBody:
required: true required: true
content: content:
application/json: application/json:
schema: schema:
properties: type: object
creationDate: allOf:
type: number - $ref: ../components/schemas/webhook-base-event.yaml
description: The date when the event was created (milliseconds since the Unix epoch). - properties:
example: 1620000000000
event: event:
type: string
description: Event type identifier.
example: recordingStarted example: recordingStarted
data: data:
properties: type: object
recordingId: required:
type: string - recordingId
description: The unique identifier of the recording. - roomId
example: room-123--EG_XYZ--XX445 - status
roomId: allOf:
type: string - $ref: ../components/schemas/recording-base.yaml
description: The ID of the room where the recording was made. - properties:
example: room-123
status: status:
type: string type: string
enum: [STARTING]
description: The status of the recording. description: The status of the recording.
example: STARTING example: STARTING
filename:
type: string
description: The name of the recording file.
example: room-123--XX445.mp4
startDate:
type: number
description: The date when the recording started (milliseconds since the Unix epoch).
example: 1620000000000
responses: responses:
'200': '200':
description: Webhook received successfully $ref: ../components/responses/webhook-success.yaml
recordingUpdated: recordingUpdated:
post: post:
summary: Recording updated summary: Recording updated
@ -61,48 +49,35 @@ recordingUpdated:
parameters: parameters:
- $ref: ../components/parameters/x-timestamp.yaml - $ref: ../components/parameters/x-timestamp.yaml
- $ref: ../components/parameters/x-signature.yaml - $ref: ../components/parameters/x-signature.yaml
# TODO: Use defined schema for request body
requestBody: requestBody:
required: true required: true
content: content:
application/json: application/json:
schema: schema:
type: object type: object
properties: allOf:
creationDate: - $ref: ../components/schemas/webhook-base-event.yaml
type: number - properties:
description: The date when the event was created (milliseconds since the Unix epoch).
example: 1620000000000
event: event:
type: string
description: Event type identifier.
example: recordingUpdated example: recordingUpdated
data: data:
properties: type: object
recordingId: required:
type: string - recordingId
description: The unique identifier of the recording. - roomId
example: room-123--EG_XYZ--XX445 - status
roomId: allOf:
type: string - $ref: ../components/schemas/recording-base.yaml
description: The ID of the room where the recording was made. - properties:
example: room-123
status: status:
type: string type: string
enum: [ACTIVE, ENDING] enum: [ACTIVE, ENDING]
description: The status of the recording. description: The status of the recording.
example: ACTIVE example: ACTIVE
filename:
type: string
description: The name of the recording file.
example: room-123--XX445.mp4
startDate:
type: number
description: The date when the recording started (milliseconds since the Unix epoch).
example: 1620000000000
responses: responses:
'200': '200':
description: Webhook received successfully $ref: ../components/responses/webhook-success.yaml
recordingEnded: recordingEnded:
post: post:
summary: Recording ended summary: Recording ended
@ -114,45 +89,32 @@ recordingEnded:
parameters: parameters:
- $ref: ../components/parameters/x-timestamp.yaml - $ref: ../components/parameters/x-timestamp.yaml
- $ref: ../components/parameters/x-signature.yaml - $ref: ../components/parameters/x-signature.yaml
# TODO: Use defined schema for request body
requestBody: requestBody:
required: true required: true
content: content:
application/json: application/json:
schema: schema:
type: object type: object
properties: allOf:
creationDate: - $ref: ../components/schemas/webhook-base-event.yaml
type: number - properties:
description: The date when the event was created (milliseconds since the Unix epoch).
example: 1620000000000
event: event:
type: string
description: Event type identifier.
example: recordingEnded example: recordingEnded
data: data:
properties: type: object
recordingId: required:
type: string - recordingId
description: The unique identifier of the recording. - roomId
example: room-123--EG_XYZ--XX445 - status
roomId: - endDate
type: string allOf:
description: The ID of the room where the recording was made. - $ref: ../components/schemas/recording-base.yaml
example: room-123 - properties:
status: status:
type: string type: string
enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED] enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED]
description: The status of the recording. description: The status of the recording.
example: COMPLETE example: COMPLETE
filename:
type: string
description: The name of the recording file.
example: room-123--XX445.mp4
startDate:
type: number
description: The date when the recording started (milliseconds since the Unix epoch).
example: 1620000000000
endDate: endDate:
type: number type: number
description: The date when the recording ended (milliseconds since the Unix epoch). description: The date when the recording ended (milliseconds since the Unix epoch).
@ -169,7 +131,58 @@ recordingEnded:
type: string type: string
description: Additional details about the recording. description: Additional details about the recording.
example: Stopped using API example: Stopped using API
responses: responses:
'200': '200':
description: Webhook received successfully $ref: ../components/responses/webhook-success.yaml
meetingStarted:
post:
summary: Meeting started
description: >
This webhook is triggered when a meeting starts.
operationId: meetingStartedWebhook
parameters:
- $ref: ../components/parameters/x-timestamp.yaml
- $ref: ../components/parameters/x-signature.yaml
requestBody:
required: true
content:
application/json:
schema:
type: object
allOf:
- $ref: ../components/schemas/webhook-base-event.yaml
- properties:
event:
example: meetingStarted
data:
$ref: ../components/schemas/meet-room.yaml
responses:
'200':
$ref: ../components/responses/webhook-success.yaml
meetingEnded:
post:
summary: Meeting ended
description: >
This webhook is triggered when a meeting ends.
operationId: meetingEndedWebhook
parameters:
- $ref: ../components/parameters/x-timestamp.yaml
- $ref: ../components/parameters/x-signature.yaml
requestBody:
required: true
content:
application/json:
schema:
type: object
allOf:
- $ref: ../components/schemas/webhook-base-event.yaml
- properties:
event:
example: meetingEnded
data:
$ref: ../components/schemas/meet-room.yaml
responses:
'200':
$ref: ../components/responses/webhook-success.yaml