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" } } ```