Vyond Webhook API
APIs for managing webhook ## Verifying Vyond Signatures Vyond webhook events are sent with a signature, which the destination server can use to verify that the events are authentic from Vyond. It is recommended to verify the signature before processing each webhook event. ### How to verify our signatures? 1. Fetch the raw request body. ``` const express = require('express'); const app = express(); app.use(express.json({ verify: (req, res, buf, encoding) => { req.rawBody = buf.toString(encoding || 'utf-8'); }, })); ``` 2. Extract the timestamp from the request header `x-vyond-request-timestamp` and the signature from the request header `x-vyond-signature`. ``` const timestamp = req.headers['x-vyond-request-timestamp']; const signature = req.headers['x-vyond-signature']; ``` 3. Create a message by concatenating the timestamp and the raw request body together, using a colon (:) as a delimiter. ``` const message = `${timestamp}:${req.rawBody}`; ``` 4. Verify the signature, an HMAC created using the SHA256 hash function, using the webhook secret as a key. ``` const { webcrypto } = require('node:crypto'); const secret = 'your_webhook_secret'; const enc = new TextEncoder(); const key = await webcrypto.subtle.importKey( 'raw', enc.encode(secret), { name: 'HMAC', hash: { name: 'SHA-256' }, }, false, ['verify'], ); const isValid = await webcrypto.subtle.verify( { name: 'HMAC' }, key, Buffer.from(signature, 'hex'), enc.encode(message), ); ``` 5. To enhance security and mitigate the risk of replay attacks, consider verifying the timestamp. Reject requests containing timestamps older than a defined tolerance, such as ten minutes, to ensure that the events are recent and valid. ## Webhook events ### Event body type definition ```typescript type WebhookEventBody = { event: string; // Refer to API for possible event types data?: Record; // Differ based on event type // Exists if it is a failure event error?: { code: string; }; }; ``` ### Sample events **Video generation succeeded** Note: `expiredAt` is when the `downloadUrl` will expire. ```json { "event": "video_generation.succeeded", "data": { "type": "vyondGo", "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "videoId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", "status": "success", "name": "Video name", "url": "https://app.vyond.org/videos/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy", "downloadUrl": "{downloadUrl}", "expiredAt": "2025-01-28T01:42:05.831Z" } } ``` **Video generation failed** ```json { "event": "video_generation.failed", "data": { "type": "vyondGo", "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "videoId": null, "status": "failed", "name": null, "url": null }, "error": { "code": "UNSUITABLE_CONTENT" } } ``` **Turbo generation succeeded** Note: `id` is the Turbo video generation task (thread) ID. `expiredAt` is when the `downloadUrl` will expire. `turboThreadUrl` is the webpage URL for you to view the chat and progress. ```json { "event": "turbo_generation.succeeded", "data": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "completed", "turboThreadUrl": "https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "downloadUrl": "{downloadUrl}", "creditConsumed": 10, "expiredAt": "2025-01-28T01:42:05.831Z" } } ``` **Turbo generation failed** Note: `error.code`: `TIMEOUT` / `GENERATION_FAILED`. ```json { "event": "turbo_generation.failed", "data": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "failed", "turboThreadUrl": "https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, "error": { "code": "GENERATION_FAILED" } } ``` **Turbo generation cancelled** ```json { "event": "turbo_generation.cancelled", "data": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "cancelled", "turboThreadUrl": "https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, "error": { "code": "CANCELLED" } } ```
Documentation
Specifications
openapi: 3.2.0
info:
title: Vyond API Documentation Webhook API
version: 1.1.0
description: "APIs for managing webhook\n\n## Verifying Vyond Signatures\n\nVyond webhook events are\
\ sent with a signature, which the destination server can use to verify that the events are authentic\
\ from Vyond. It is recommended to verify the signature before processing each webhook event.\n\n\
### How to verify our signatures?\n\n1. Fetch the raw request body.\n\n ```\n const express\
\ = require('express');\n const app = express();\n\n app.use(express.json({\n verify:\
\ (req, res, buf, encoding) => {\n req.rawBody = buf.toString(encoding || 'utf-8');\n \
\ },\n }));\n ```\n\n2. Extract the timestamp from the request header `x-vyond-request-timestamp`\
\ and the signature from the request header `x-vyond-signature`.\n\n ```\n const timestamp =\
\ req.headers['x-vyond-request-timestamp'];\n const signature = req.headers['x-vyond-signature'];\n\
\ ```\n\n3. Create a message by concatenating the timestamp and the raw request body together,\
\ using a colon (:) as a delimiter.\n\n ```\n const message = `${timestamp}:${req.rawBody}`;\n\
\ ```\n\n4. Verify the signature, an HMAC created using the SHA256 hash function, using the webhook\
\ secret as a key.\n\n ```\n const { webcrypto } = require('node:crypto');\n\n const secret\
\ = 'your_webhook_secret';\n const enc = new TextEncoder();\n const key = await webcrypto.subtle.importKey(\n\
\ 'raw',\n enc.encode(secret),\n {\n name: 'HMAC',\n hash:\
\ { name: 'SHA-256' },\n },\n false,\n ['verify'],\n );\n\n const isValid\
\ = await webcrypto.subtle.verify(\n { name: 'HMAC' },\n key,\n Buffer.from(signature,\
\ 'hex'),\n enc.encode(message),\n );\n ```\n\n5. To enhance security and mitigate the\
\ risk of replay attacks, consider verifying the timestamp. Reject requests containing timestamps\
\ older than a defined tolerance, such as ten minutes, to ensure that the events are recent and valid.\n\
\n## Webhook events\n\n### Event body type definition\n\n```typescript\ntype WebhookEventBody = {\n\
\ event: string; // Refer to API for possible event types\n data?: Record<string, unknown>;\
\ // Differ based on event type\n\n // Exists if it is a failure event\n error?: {\n \
\ code: string;\n };\n};\n```\n\n### Sample events\n\n**Video generation succeeded**\n\nNote: `expiredAt`\
\ is when the `downloadUrl` will expire.\n\n```json\n{\n \"event\": \"video_generation.succeeded\"\
,\n \"data\": {\n \"type\": \"vyondGo\",\n \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
,\n \"videoId\": \"yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\",\n \"status\": \"success\"\
,\n \"name\": \"Video name\",\n \"url\": \"https://app.vyond.org/videos/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\"\
,\n \"downloadUrl\": \"{downloadUrl}\",\n \"expiredAt\": \"2025-01-28T01:42:05.831Z\"\
\n }\n}\n```\n\n**Video generation failed**\n\n```json\n{\n \"event\": \"video_generation.failed\"\
,\n \"data\": {\n \"type\": \"vyondGo\",\n \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
,\n \"videoId\": null,\n \"status\": \"failed\",\n \"name\": null,\n \"\
url\": null\n },\n \"error\": {\n \"code\": \"UNSUITABLE_CONTENT\"\n }\n}\n```\n\n\
**Turbo generation succeeded**\n\nNote: `id` is the Turbo video generation task (thread) ID. `expiredAt`\
\ is when the `downloadUrl` will expire. `turboThreadUrl` is the webpage URL for you to view the chat\
\ and progress.\n\n```json\n{\n \"event\": \"turbo_generation.succeeded\",\n \"data\": {\n \
\ \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"status\": \"completed\",\n \
\ \"turboThreadUrl\": \"https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
,\n \"downloadUrl\": \"{downloadUrl}\",\n \"creditConsumed\": 10,\n \"expiredAt\"\
: \"2025-01-28T01:42:05.831Z\"\n }\n}\n```\n\n**Turbo generation failed**\n\nNote: `error.code`:\
\ `TIMEOUT` / `GENERATION_FAILED`.\n\n```json\n{\n \"event\": \"turbo_generation.failed\",\n \
\ \"data\": {\n \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"status\": \"\
failed\",\n \"turboThreadUrl\": \"https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
\n },\n \"error\": {\n \"code\": \"GENERATION_FAILED\"\n }\n}\n```\n\n**Turbo generation\
\ cancelled**\n\n```json\n{\n \"event\": \"turbo_generation.cancelled\",\n \"data\": {\n \
\ \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"status\": \"cancelled\",\n \
\ \"turboThreadUrl\": \"https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n\
\ },\n \"error\": {\n \"code\": \"CANCELLED\"\n }\n}\n```\n"
tags:
- name: Webhook
description: "APIs for managing webhook\n\n## Verifying Vyond Signatures\n\nVyond webhook events are\
\ sent with a signature, which the destination server can use to verify that the events are authentic\
\ from Vyond. It is recommended to verify the signature before processing each webhook event.\n\n\
### How to verify our signatures?\n\n1. Fetch the raw request body.\n\n ```\n const express\
\ = require('express');\n const app = express();\n\n app.use(express.json({\n verify:\
\ (req, res, buf, encoding) => {\n req.rawBody = buf.toString(encoding || 'utf-8');\n \
\ },\n }));\n ```\n\n2. Extract the timestamp from the request header `x-vyond-request-timestamp`\
\ and the signature from the request header `x-vyond-signature`.\n\n ```\n const timestamp =\
\ req.headers['x-vyond-request-timestamp'];\n const signature = req.headers['x-vyond-signature'];\n\
\ ```\n\n3. Create a message by concatenating the timestamp and the raw request body together,\
\ using a colon (:) as a delimiter.\n\n ```\n const message = `${timestamp}:${req.rawBody}`;\n\
\ ```\n\n4. Verify the signature, an HMAC created using the SHA256 hash function, using the webhook\
\ secret as a key.\n\n ```\n const { webcrypto } = require('node:crypto');\n\n const secret\
\ = 'your_webhook_secret';\n const enc = new TextEncoder();\n const key = await webcrypto.subtle.importKey(\n\
\ 'raw',\n enc.encode(secret),\n {\n name: 'HMAC',\n hash:\
\ { name: 'SHA-256' },\n },\n false,\n ['verify'],\n );\n\n const isValid\
\ = await webcrypto.subtle.verify(\n { name: 'HMAC' },\n key,\n Buffer.from(signature,\
\ 'hex'),\n enc.encode(message),\n );\n ```\n\n5. To enhance security and mitigate the\
\ risk of replay attacks, consider verifying the timestamp. Reject requests containing timestamps\
\ older than a defined tolerance, such as ten minutes, to ensure that the events are recent and valid.\n\
\n## Webhook events\n\n### Event body type definition\n\n```typescript\ntype WebhookEventBody = {\n\
\ event: string; // Refer to API for possible event types\n data?: Record<string, unknown>;\
\ // Differ based on event type\n\n // Exists if it is a failure event\n error?: {\n \
\ code: string;\n };\n};\n```\n\n### Sample events\n\n**Video generation succeeded**\n\nNote: `expiredAt`\
\ is when the `downloadUrl` will expire.\n\n```json\n{\n \"event\": \"video_generation.succeeded\"\
,\n \"data\": {\n \"type\": \"vyondGo\",\n \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
,\n \"videoId\": \"yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\",\n \"status\": \"success\"\
,\n \"name\": \"Video name\",\n \"url\": \"https://app.vyond.org/videos/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\"\
,\n \"downloadUrl\": \"{downloadUrl}\",\n \"expiredAt\": \"2025-01-28T01:42:05.831Z\"\
\n }\n}\n```\n\n**Video generation failed**\n\n```json\n{\n \"event\": \"video_generation.failed\"\
,\n \"data\": {\n \"type\": \"vyondGo\",\n \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
,\n \"videoId\": null,\n \"status\": \"failed\",\n \"name\": null,\n \"\
url\": null\n },\n \"error\": {\n \"code\": \"UNSUITABLE_CONTENT\"\n }\n}\n```\n\n\
**Turbo generation succeeded**\n\nNote: `id` is the Turbo video generation task (thread) ID. `expiredAt`\
\ is when the `downloadUrl` will expire. `turboThreadUrl` is the webpage URL for you to view the chat\
\ and progress.\n\n```json\n{\n \"event\": \"turbo_generation.succeeded\",\n \"data\": {\n \
\ \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"status\": \"completed\",\n \
\ \"turboThreadUrl\": \"https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
,\n \"downloadUrl\": \"{downloadUrl}\",\n \"creditConsumed\": 10,\n \"expiredAt\"\
: \"2025-01-28T01:42:05.831Z\"\n }\n}\n```\n\n**Turbo generation failed**\n\nNote: `error.code`:\
\ `TIMEOUT` / `GENERATION_FAILED`.\n\n```json\n{\n \"event\": \"turbo_generation.failed\",\n \
\ \"data\": {\n \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"status\": \"\
failed\",\n \"turboThreadUrl\": \"https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\
\n },\n \"error\": {\n \"code\": \"GENERATION_FAILED\"\n }\n}\n```\n\n**Turbo generation\
\ cancelled**\n\n```json\n{\n \"event\": \"turbo_generation.cancelled\",\n \"data\": {\n \
\ \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"status\": \"cancelled\",\n \
\ \"turboThreadUrl\": \"https://app.vyond.com/turbo/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n\
\ },\n \"error\": {\n \"code\": \"CANCELLED\"\n }\n}\n```\n"
paths:
/rest/v1/webhooks/:
get:
operationId: WebhookController.getWebhooks
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookListResBody'
description: List of webhooks
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Forbidden - invalid owner type (non-user token)
'429':
description: Too Many Requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Internal Server Error - unexpected error while retrieving webhooks
summary: List webhooks
tags:
- Webhook
security:
- bearer: []
description: List webhooks owned by the user
post:
operationId: WebhookController.createWebhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCreateReqBody'
description: WebhookCreateReqBody
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookWithSecret'
description: Created webhook
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Forbidden - invalid owner type (non-user token)
'429':
description: Too Many Requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Internal Server Error - unexpected error while creating webhook
summary: Create webhook
tags:
- Webhook
security:
- bearer: []
description: Register a new webhook on Vyond, default enabled
/rest/v1/webhooks/{webhookId}:
patch:
operationId: WebhookController.updateWebhook
parameters:
- in: path
name: webhookId
required: true
schema:
pattern: '[^\/#\?]+?'
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookUpdateReqBody'
description: WebhookUpdateReqBody
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
description: Updated webhook
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Forbidden - invalid owner type (non-user token)
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Not Found - webhook does not exist or does not belong to the user
'429':
description: Too Many Requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Internal Server Error - unexpected error while updating webhook
summary: Update webhook
tags:
- Webhook
security:
- bearer: []
description: Update an existing webhook
delete:
operationId: WebhookController.deleteWebhook
parameters:
- in: path
name: webhookId
required: true
schema:
pattern: '[^\/#\?]+?'
type: string
responses:
'204':
content:
application/json: {}
description: Webhook is deleted successfully
'401':
description: Unauthorized - missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Forbidden - invalid owner type (non-user token)
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Not Found - webhook does not exist or does not belong to the user
'429':
description: Too Many Requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
description: Internal Server Error - unexpected error while deleting webhook
summary: Delete webhook
tags:
- Webhook
security:
- bearer: []
description: Delete an existing webhook
components:
schemas:
WebhookUpdateReqBody:
properties:
name:
type: string
description: Name of the webhook
url:
format: url
type: string
description: URL of the webhook, protocol must be https
events:
items:
enum:
- video_generation.succeeded
- video_generation.failed
- video_export.succeeded
- video_export.failed
- turbo_generation.succeeded
- turbo_generation.failed
type: string
type: array
description: Events that the webhook subscribed to
status:
type: string
enum:
- enabled
- disabled
description: Status of the webhook
type: object
WebhookCreateReqBody:
properties:
name:
type: string
description: Name of the webhook
url:
format: url
type: string
description: URL of the webhook, protocol must be https
events:
items:
enum:
- video_generation.succeeded
- video_generation.failed
- video_export.succeeded
- video_export.failed
- turbo_generation.succeeded
- turbo_generation.failed
type: string
type: array
description: Events that the webhook subscribed to
type: object
required:
- url
- events
ValidationDetail:
properties:
property:
type: string
description: The property that failed validation
message:
items:
type: string
type: array
description: Validation error messages for the property
type: object
required:
- property
- message
WebhookListResBody:
properties:
data:
items:
$ref: '#/components/schemas/Webhook'
type: array
description: List of webhooks
type: object
required:
- data
ApiErrorResponse:
properties:
err:
type: string
description: Error code identifying the specific error
reason:
type: string
description: Additional reason describing why the error occurred
message:
type: string
description: Error message, used as an alternative to reason for non-enumerated error messages
scimType:
type: string
description: SCIM error type, present on SCIM 409 Conflict responses (e.g. uniqueness)
details:
items:
$ref: '#/components/schemas/ValidationDetail'
type: array
description: Validation error details, present when err is REQUEST_VALIDATION_FAILED
type: object
required:
- err
Webhook:
properties:
webhookId:
type: string
description: ID of the webhook
name:
type: string
description: Name of the webhook
url:
format: url
type: string
description: URL of the webhook, must be in https
events:
items:
enum:
- video_generation.succeeded
- video_generation.failed
- video_export.succeeded
- video_export.failed
- turbo_generation.succeeded
- turbo_generation.failed
type: string
type: array
description: Events that the webhook subscribed to
status:
type: string
enum:
- enabled
- disabled
description: Status of the webhook
type: object
required:
- webhookId
- url
- events
- status
WebhookWithSecret:
properties:
secret:
type: string
description: Secret of the webhook which is required to [verify signatures](#tag/Webhook/Verifying-Vyond-Signatures)
from Vyond, note that this secret is only available at time of webhook creation
webhookId:
type: string
description: ID of the webhook
name:
type: string
description: Name of the webhook
url:
format: url
type: string
description: URL of the webhook, must be in https
events:
items:
enum:
- video_generation.succeeded
- video_generation.failed
- video_export.succeeded
- video_export.failed
- turbo_generation.succeeded
- turbo_generation.failed
type: string
type: array
description: Events that the webhook subscribed to
status:
type: string
enum:
- enabled
- disabled
description: Status of the webhook
type: object
required:
- secret
- webhookId
- url
- events
- status
securitySchemes:
bearer:
type: http
scheme: bearer