Webhook Video Captioning API

Fire a render task, get a signed event when it lands

Stop polling for render status. Attach a notification webhook to a captioning task and ZapCap POSTs a signed event to your endpoint the moment the render completes — with the renderUrl and transcriptUrl ready to fetch. Built for async pipelines that need to react, not wait.

Create API key Read API docs

Signed events · eventId dedupe · automatic retries · no polling loop

Workflow Transcripts Output modes Pricing Proof Quickstart FAQ

Push, not poll

How you find out a render is done

Caption rendering is asynchronous. The difference between a fragile integration and a robust one is how your system learns the job finished.

OPTION 01

Tight polling loop

GET the task on a timer

Simple to start
Wasted requests while queued
Latency between polls
You build the scheduler

OPTION 02

Manual checking

Dashboard refresh / human

Fine for one-offs
Doesn't scale
No pipeline automation
Slow hand-offs

OPTION 03 · YOU ARE HERE

ZapCap · notification webhooks

Signed push event on completion

Event POSTed on completion
HMAC-signed, dedupe on eventId
Automatic retries on failure
No polling loop to maintain

OPTION 04

No status at all

Fire-and-forget renders

Least code
No idea when it is ready
No failure handling
Unfit for production

API workflow

How the Webhook Video Captioning API works

Upload the video, create a task with a notification object on the body, and ZapCap POSTs a signed event to your recipient URL when the render completes. The event carries renderUrl and transcriptUrl — fetch them and move on.

1
Upload your video
POST the file to /videos. We stream it to storage and hand you back a videoId.
POSTPOST /videos
2
Create the captioning task
One POST starts transcription, styling and rendering with your chosen template. Add a notification webhook to skip polling.
POSTPOST /videos/:id/task
3
Receive the webhook
We POST status updates to your endpoint as the render moves through transcribing → rendering → completed.
HOOKPOST → your URL
4
Download the finished render
Burned-in subtitles, served from a global CDN. No watermark. MP4 ready for any social platform.
GETGET renderUrl

Step 1 / 4·~2s

1import { readFileSync } from "node:fs";

3const form = new FormData();

4form.append(

5 "file",

6 new Blob([readFileSync("clip.mp4")]),

7 "clip.mp4",

8);

10const { id: videoId } = await fetch(

11 "https://api.zapcap.ai/videos",

12 {

13 method: "POST",

14 headers: { "x-api-key": process.env.ZAPCAP_KEY! },

15 body: form,

16 },

17).then(r => r.json());

POST /videos·Upload your video

Two ways to drive the render

Webhook Video Captioning API transcript options

Auto-transcribe

Let ZapCap transcribe and time the captions as part of the task. You can also subscribe to transcription events so your pipeline reacts before the render even starts.

Set notificationsFor on the task to choose which events you receive
Inspect / edit the transcript via PUT /videos/:id/task/:taskId/transcript
React to a render event to fetch the finished MP4

Bring your own transcript

Send approved cues and skip transcription — the render event still fires on completion exactly the same way, so your async flow is identical.

Supported via the SRT-to-burned-in workflow
Same signed render event, same eventId dedupe
Preserve approved wording all the way to the webhook payload

What the event delivers

Webhook Video Captioning API output modes

Most common

Burned-in MP4

The completed render event carries a presigned renderUrl for the captioned h264 MP4 — fetch it the moment the event lands.

.mp4 · h264

Editor-friendly

Transparent overlay

Request an alpha overlay and the render event delivers a presigned link to the ProRes 4444 or VP9 output the same way.

.mov ProRes 4444 · .webm VP9 alpha

Compatibility

Green-screen layer

Green-screen renders deliver through the same webhook event — a presigned link to the #04F404-backed MP4.

.mp4 · #04F404 backdrop

The renderUrl in the webhook payload is a presigned link with a 60-minute TTL — download promptly or re-fetch the task status for a fresh URL. The transcriptUrl is delivered alongside it.

Simple API credits

Per-minute, usage-based credits

Webhooks are part of the API at no extra cost — you pay only for the minutes you render. See pricing for the full multiplier table.

Webhook notifications included, no add-on fee
Top up credits to keep tasks flowing in production
Volume credits available at scale

$0.10 / min

Indicative starting rate. Final pricing depends on render mode and output format. API access requires a Pro plan plus credits.

View full pricing Talk to us about volume

Customer · Anonymized

A video platform replaced a polling scheduler with notification webhooks and let captioned renders flow straight into their pipeline on completion

Each task carries a recipient URL; the signed render event triggers the next step automatically. Dedupe on eventId makes retries safe, so duplicate deliveries never double-process a render.

Read case study

push

Events replaced the polling loop

eventId

Idempotent handling of retries

signed

x-signature verified on every event

auto

Renders flow into the pipeline

Developer quickstart

Attach a webhook when you create the task

The webhook configuration lives on the task request. ZapCap signs each POST to your recipient URL; verify the x-signature header and dedupe by eventId before storing the renderUrl.

notification.type is webhook and recipient is your public HTTPS endpoint
notificationsFor controls transcript, render, and render-progress events
Return a 2xx response only after the event is accepted or safely deduped

{
  "templateId": "d46bb0da-cce0-4507-909d-fa8904fb8ed7",
  "autoApprove": true,
  "language": "en",
  "notification": {
    "type": "webhook",
    "notificationsFor": ["render"],
    "recipient": "https://your.app/api/zapcap-webhook"
  }
}

About webhook video captioning

Add a notification object to the task body when you create the render task: an object with type "webhook", a notificationsFor array (for example ["render"]), and your recipient URL. ZapCap then POSTs a JSON event to that URL when the events you subscribed to occur. Webhooks are how every render on ZapCap’s video captioning API reports completion.

The render event payload includes eventId, event (either "completed" or "failed"), taskId, notificationFor set to "render", a transcriptUrl, and a renderUrl. The renderUrl and transcriptUrl are presigned links you fetch directly.

Each delivery includes an x-signature header — an HMAC-SHA256 signature computed over the payload with your shared secret. Recompute the HMAC on your side and compare; reject the request if it does not match.

Dedupe on eventId. Because webhooks can be retried, the same render event may be delivered more than once. Record the eventId of every event you handle and ignore any eventId you have already processed, so retries are idempotent.

Failed webhook deliveries are retried automatically. Combined with eventId dedupe, that means a transient outage on your side does not lose the event — you receive it on a later retry and skip it if you somehow already handled it.

The renderUrl in the payload is a presigned link with a 60-minute TTL. Download the file promptly when the event arrives; if it expires, fetch the task status again with GET /videos/{videoId}/task/{taskId} to get a fresh downloadUrl.

Yes. Webhooks are optional. You can poll GET /videos/{videoId}/task/{taskId} until the status reports completed, which returns the downloadUrl. Webhooks simply remove the polling loop for production pipelines.

Keep exploring

Build event-driven captioning through the API

Create a key on a Pro plan and buy credits in the dashboard.

Create API key Read API docs

Webhook Video Captioning API

Fire a render task, get a signed event when it lands

How you find out a render is done

How the Webhook Video Captioning API works

Upload your video

Create the captioning task

Receive the webhook

Download the finished render