API and webhooks

Create a key under Settings → Agents. A key acts as you in one workspace. Webhooks are managed in the same place by owners and admins.

Authentication

Send the key as Authorization: Bearer rk_…. CORS is open, so the API also works from a browser extension or a small script.

List videos

GET /api/v1/videos returns the videos the key's owner can see in that workspace.

curl 'https://vertov.app/api/v1/videos' \
  -H 'Authorization: Bearer rk_your_key'

{ "videos": [{ "id": "k3J9x", "url": "https://vertov.app/k3J9x", "title": "Homepage walkthrough",
  "duration": 94, "status": "ready", "createdAt": "2026-11-01T10:12:00Z", "owner": "Priya", "snippet": "..." }] }

Upload a video

POST /api/v1/videos with the file as the request body. The response carries the share link; the video is playable as soon as it returns.

curl -X POST 'https://vertov.app/api/v1/videos?title=What%20I%20changed' \
  -H 'Authorization: Bearer rk_your_key' \
  -H 'Content-Type: video/webm' \
  --data-binary @recording.webm

Webhooks

Each event is a POST with a JSON body. Respond with any 2xx within 8 seconds. Deliveries are sent once, with no automatic retries, so treat them as a fast signal and list the videos if you need to catch up. Endpoints must be public https addresses.

EventSent whendata fields
video.readyA recording, upload or import finished and is playable.id, url, title, duration
video.viewedSomeone other than the owner opened a video (one per viewer per video).id, url, title, country, referrer
comment.createdA signed-in viewer or a named guest commented.id, videoId, url, author, text, timestamp
POST https://your-server.example/hooks/vertov
webhook-id: msg_2f9c0a...
webhook-timestamp: 1793527920
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2/3+hk0qlyF3RcE=

{
  "type": "video.ready",
  "timestamp": "2026-11-01T10:12:00.000Z",
  "data": { "id": "k3J9x", "url": "https://vertov.app/k3J9x", "title": "Homepage walkthrough", "duration": 94 }
}

Verify the signature

Requests follow the Standard Webhooks scheme, so any of its libraries work with your whsec_… secret. The signature is the base64 HMAC-SHA256 of webhook-id.webhook-timestamp.body, keyed with the decoded secret. Check it against the raw body and reject old timestamps.

import { createHmac, timingSafeEqual } from "node:crypto"

// rawBody must be the exact request body string, before any JSON parsing.
export function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"]
  const timestamp = headers["webhook-timestamp"]
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false // replay window

  const key = Buffer.from(secret.replace("whsec_", ""), "base64")
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64")

  return headers["webhook-signature"].split(" ").some((entry) => {
    const [version, signature] = entry.split(",")
    return version === "v1" && signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  })
}
Commands and recent recordings
Actions
Go to
↑ ↓ Select↵ OpenEsc Close