Webhooks & Automations for Studios

Every delivery is a JSON body shaped like this:

{
  "event": "recording.ready",
  "event_id": "b1f2…",          // unique per delivery, use to de-duplicate retries
  "version": "1",
  "timestamp": "2026-07-05T14:41:00Z",  // when the webhook fired
  "account_id": "…",
  "session_url": "https://app.suretake.io/share/…",  // shareable preview/download page
  "show":    { "id": "…", "name": "My Podcast" },
  "session": {
    "id": "…",
    "name": "Episode 12",
    "date": "2026-07-05",
    "started_at": "2026-07-05T14:03:00Z",  // full timestamp, for sorting
    "notes": "00:12:30 New topic\n00:41:05 Ad read",  // notes + markers, as text
    "notes_url": "https://app.suretake.io/api/share/…/notes"  // same notes as a .txt download
  },
  "client":  { "email": "guest@example.com", "name": "Jane Guest" },
  "track_count": 2,             // number of participant tracks in "tracks" below
  "tracks": [                   // ONLY individual participant recordings, no backup here
    {
      "type": "browser",       // an individual participant's local recording
      "recording_id": "…",
      "participant_id": "…",
      "name": "Host",
      "file_url": "https://…/host.mp4",
      "synced_url": null,       // present only if the participant joined late (time-aligned copy)
      "duration_seconds": 3120
    },
    {
      "type": "browser",
      "recording_id": "…",
      "participant_id": "…",
      "name": "Jane Guest",
      "file_url": "https://…/guest.mp4",
      "synced_url": null,
      "duration_seconds": 3115
    }
  ],
  // media_urls: flat "just grab these" list of participant files (same order as "tracks").
  // A no-code shortcut: map straight into a multi-file field, no code step. Already the
  // right file per track: the synced version when a track needed aligning, else file_url.
  "media_urls": [ "https://…/host.mp4", "https://…/guest.mp4" ],
  // The server-side recording of everyone together, kept OUT of "tracks" on purpose so
  // you can import just the participant recordings. Use it as a safety net if you want it.
  "combined_backup_url": "https://…/combined.mp4",
  "transcript": { "url": "https://…/transcript.docx" }  // or null (see Transcripts below)
}

A few notes: tracks holds only the individual participant recordings. It's an array whose length varies with the number of participants, so always iterate it rather than assuming a fixed count. The combined backup (the single server-side recording of everyone together) is deliberately not in tracks; it's provided separately as combined_backup_url, so you can import just the participant files and treat the backup as an optional safety net.

They point at the same participant recordings, just two shapes for two kinds of consumer. tracks is the rich version: an array of objects with the full detail for each recording (participant name, duration_seconds, the recording_id, each track's file_url, and a synced_url when someone joined late). Reach for it when you want to label, organize, or make decisions per file.

media_urls is the convenience version: a flat array of just the files to grab, in the same order. It exists purely to make no-code automations easy. Tools like Zapier, Make, and n8n often can't pull a nested field out of an array of objects without a code/formatter step, so media_urls lets you map the whole list straight into a “multiple files” input. It's also the authoritative “just grab these” list: for any track that needed time-aligning (a late joiner), media_urls already points at the synced version, so you never have to check synced_url yourself. Every URL in it is the file you actually want.

For example, in a Descript import step you can map its media field directly to media_urls and it'll pull in every participant track at once, with no formatter or code step needed. Use whichever fits your tool; the combined backup is intentionally in neither, on combined_backup_url.

The webhook hands you direct download links (media_urls). How you pull them into folders is up to you. First, a word on file sizes:

A recording's media files are large, a combined backup can be hundreds of MB, and many no-code “upload to cloud storage” steps have file-size limits (for example, Zapier's Dropbox action caps around 100 MB, and some actions far lower). So routing a full recording through an automation tool into Dropbox / Drive often won't work. The download has to happen somewhere without that size ceiling:

Most reliable (any size): a small script (Python, a Node function, etc.) that downloads the URLs straight into a local or network folder, with no middleman and no size limit. Trigger it from the webhook, or run it on an always-on machine that reads the URLs from wherever you track jobs.

No-code, within limits: Zapier, Make, and n8n work well for the small files (the notes and transcript), and for media only if your destination pulls from the URL directly (its own API, a cloud function, a tool like rclone) rather than passing the file through the automation tool.

Bridge from your existing tools: if your order- or project-management software can hold the URLs, fetch from there. For example, a Google Sheet of links plus a script that pulls each job's files into the right folder.

There are a variety of ways to do this in Descript, depending on the tools you use. (Note that Descript's own API is currently invite-only, so a fully custom integration may not be open to you yet.)

One approach we've experimented with is Zapier plus Descript's built-in integration, triggered by this webhook. We start the Zap with a “Catch Hook” trigger (Webhooks by Zapier) and paste in the SureTake webhook URL. Then a Descript “Import Media” action creates the project, named from the show and episode, and imports the files from media_urls. A second Descript action, “Edit Project with AI,” builds the sequence, transcribes the files, and adds the sequence to the main composition. That second step runs on Descript's built-in AI (Underlord), so it draws on your Descript account's credits.

One idea worth exploring here: session.notes (the timestamped markers your host and guests drop live during recording) rides in the same payload, so you can map it into that AI step's instructions, anything you could direct Underlord to do, you can drive from the notes taken in the moment.

We like to finish with an email notification so we know a new session is ready, and you can take it further from there, wiring in other tools like invoicing software or Slack.

One current limitation on Descript's side: new projects can only be created in your personal folder.

Each request carries an X-Webhook-Signature header, an HMAC-SHA256 of the raw request body, signed with your endpoint's secret (shown once when you create the endpoint; rotate it anytime). Recompute it on your end and compare. A match proves the request is genuine and untampered:

// Node.js: verify the request really came from SureTake
const crypto = require("crypto");

const signature = req.headers["x-webhook-signature"];
const expected = crypto
  .createHmac("sha256", YOUR_ENDPOINT_SECRET)   // the secret shown when you created the endpoint
  .update(rawRequestBody)                        // the raw body bytes, before JSON.parse
  .digest("hex");

const valid =
  signature &&
  crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
// if !valid → reject the request

The request also includes an X-Webhook-Event header (recording.ready). Verifying is optional but recommended for anything sensitive. Most no-code tools (Zapier/Make) skip it and simply trust the URL, which is fine if you keep the URL private.