Events and webhooks

{
  "id": "3f6c2b0e-8a41-4c55-9d0e-2a7b9c1d4e5f",
  "type": "video.delivered",
  "version": 1,
  "createdAt": "2026-10-24T09:41:07.000Z",
  "cursor": "1842",
  "organizationId": "0b7e7c55-4a0e-4f3e-9a51-3d2c1b0a9f88",
  "videoId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "runId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "spaceId": "7d1f4c9a-2b3e-4d5f-8a6b-9c0d1e2f3a4b",
  "data": {
    "label": "Delivered"
  }
}

export PROBABLY_API_URL="https://studio.probably.co"
export PROBABLY_API_KEY="prb_..."

#!/usr/bin/env bash
# Read your organization's events from the start, ten at a time. Pass the
# page's "cursor" as "after" to read the next page.
set -euo pipefail

curl --silent --show-error --fail-with-body \
  "$PROBABLY_API_URL/api/v1/events?after=0&limit=10" \
  --header "Authorization: Bearer $PROBABLY_API_KEY"

// A webhook receiver that checks each delivery's Standard Webhooks signature
// before trusting it. Run it with Bun or Node 23.6+, with zod installed:
//   PROBABLY_WEBHOOK_SECRET=whsec_... PORT=3000 bun webhook-receiver.ts
import { createHmac, timingSafeEqual } from "node:crypto"
import { createServer } from "node:http"

import { z } from "zod"

const secret = process.env.PROBABLY_WEBHOOK_SECRET

const port = Number(process.env.PORT ?? "3000")

if (!secret?.startsWith("whsec_")) throw new Error("Set PROBABLY_WEBHOOK_SECRET to whsec_...")

// Deliveries signed longer ago than this are refused, so a captured one can't be replayed.
const toleranceSeconds = 5 * 60

// The headers each delivery is signed with.
const signed = z.object({
  "webhook-id": z.string().min(1),
  "webhook-timestamp": z.coerce.number().int(),
  "webhook-signature": z.string().min(1),
})

// The fields of an event this receiver reads; the docs list every one.
const event = z.object({
  type: z.string(),
  videoId: z.string().nullable(),
  data: z.object({ label: z.string() }),
})

/** Whether a delivery is authentic: signed with this secret, recently, over exactly this body. */
function verify(headers: z.output<typeof signed>, body: string, signingSecret: string) {
  const { "webhook-id": id, "webhook-timestamp": timestamp } = headers

  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false

  const key = Buffer.from(signingSecret.slice("whsec_".length), "base64")

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

  // The header may carry several signatures, space-separated, each "v1,<base64>".
  return headers["webhook-signature"].split(" ").some((signature) => {
    const given = Buffer.from(signature.replace(/^v1,/, ""))

    return given.length === expected.length && timingSafeEqual(given, expected)
  })
}

const server = createServer((request, response) => {
  const chunks: Buffer[] = []

  request.on("data", (chunk: Buffer) => chunks.push(chunk))
  request.on("end", () => {
    const body = Buffer.concat(chunks).toString("utf8")
    const headers = signed.safeParse(request.headers)

    if (!headers.success || !verify(headers.data, body, secret)) {
      response.writeHead(401).end()

      return
    }

    // Deliveries are at least once: skip an event whose webhook-id you've already handled.
    const delivered = event.parse(JSON.parse(body))

    console.log(`${delivered.type} for video ${delivered.videoId}: ${delivered.data.label}`)
    response.writeHead(204).end()
  })
})

server.listen(port, () => console.log(`Listening on http://localhost:${port}`))