backend: Standardize webhook parameter names and descriptions; implement schemas for webhook events
This commit is contained in:
Carlos Santos
parent
bbbb7fc0c1
commit
b613bcb53d
@ -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
|
||||||
|
|||||||
@ -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'
|
||||||
|
|||||||
@ -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
23
backend/openapi/components/schemas/recording-base.yaml
Normal 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
17
backend/openapi/components/schemas/webhook-base-event.yaml
Normal 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.
|
||||||
@ -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:
|
example: recordingStarted
|
||||||
type: string
|
data:
|
||||||
description: Event type identifier.
|
type: object
|
||||||
example: recordingStarted
|
required:
|
||||||
data:
|
- recordingId
|
||||||
properties:
|
- roomId
|
||||||
recordingId:
|
- status
|
||||||
type: string
|
allOf:
|
||||||
description: The unique identifier of the recording.
|
- $ref: ../components/schemas/recording-base.yaml
|
||||||
example: room-123--EG_XYZ--XX445
|
- properties:
|
||||||
roomId:
|
status:
|
||||||
type: string
|
type: string
|
||||||
description: The ID of the room where the recording was made.
|
enum: [STARTING]
|
||||||
example: room-123
|
description: The status of the recording.
|
||||||
status:
|
example: STARTING
|
||||||
type: string
|
|
||||||
description: The status of the recording.
|
|
||||||
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).
|
event:
|
||||||
example: 1620000000000
|
example: recordingUpdated
|
||||||
event:
|
data:
|
||||||
type: string
|
type: object
|
||||||
description: Event type identifier.
|
required:
|
||||||
example: recordingUpdated
|
- recordingId
|
||||||
data:
|
- roomId
|
||||||
properties:
|
- status
|
||||||
recordingId:
|
allOf:
|
||||||
type: string
|
- $ref: ../components/schemas/recording-base.yaml
|
||||||
description: The unique identifier of the recording.
|
- properties:
|
||||||
example: room-123--EG_XYZ--XX445
|
status:
|
||||||
roomId:
|
type: string
|
||||||
type: string
|
enum: [ACTIVE, ENDING]
|
||||||
description: The ID of the room where the recording was made.
|
description: The status of the recording.
|
||||||
example: room-123
|
example: ACTIVE
|
||||||
status:
|
|
||||||
type: string
|
|
||||||
enum: [ACTIVE, ENDING]
|
|
||||||
description: The status of the recording.
|
|
||||||
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,62 +89,100 @@ 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).
|
event:
|
||||||
example: 1620000000000
|
example: recordingEnded
|
||||||
event:
|
data:
|
||||||
type: string
|
type: object
|
||||||
description: Event type identifier.
|
required:
|
||||||
example: recordingEnded
|
- recordingId
|
||||||
data:
|
- roomId
|
||||||
properties:
|
- status
|
||||||
recordingId:
|
- endDate
|
||||||
type: string
|
allOf:
|
||||||
description: The unique identifier of the recording.
|
- $ref: ../components/schemas/recording-base.yaml
|
||||||
example: room-123--EG_XYZ--XX445
|
- properties:
|
||||||
roomId:
|
status:
|
||||||
type: string
|
type: string
|
||||||
description: The ID of the room where the recording was made.
|
enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED]
|
||||||
example: room-123
|
description: The status of the recording.
|
||||||
status:
|
example: COMPLETE
|
||||||
type: string
|
endDate:
|
||||||
enum: [COMPLETE, FAILED, ABORTED, LIMITED_REACHED]
|
type: number
|
||||||
description: The status of the recording.
|
description: The date when the recording ended (milliseconds since the Unix epoch).
|
||||||
example: COMPLETE
|
example: 1620000003600
|
||||||
filename:
|
duration:
|
||||||
type: string
|
type: number
|
||||||
description: The name of the recording file.
|
description: The duration of the recording in seconds.
|
||||||
example: room-123--XX445.mp4
|
example: 3.6
|
||||||
startDate:
|
size:
|
||||||
type: number
|
type: number
|
||||||
description: The date when the recording started (milliseconds since the Unix epoch).
|
description: The size of the recording file in bytes.
|
||||||
example: 1620000000000
|
example: 1024
|
||||||
endDate:
|
details:
|
||||||
type: number
|
type: string
|
||||||
description: The date when the recording ended (milliseconds since the Unix epoch).
|
description: Additional details about the recording.
|
||||||
example: 1620000003600
|
example: Stopped using API
|
||||||
duration:
|
|
||||||
type: number
|
|
||||||
description: The duration of the recording in seconds.
|
|
||||||
example: 3.6
|
|
||||||
size:
|
|
||||||
type: number
|
|
||||||
description: The size of the recording file in bytes.
|
|
||||||
example: 1024
|
|
||||||
details:
|
|
||||||
type: string
|
|
||||||
description: Additional details about the recording.
|
|
||||||
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
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user