Transcript API
Back to API Docs

What is a Webhook?

1The Simple Explanation

A webhook is like giving someone your phone number so they can call you when something happens, instead of you constantly calling them to check.

In technical terms: a webhook is an automated message sent from one application to another when a specific event occurs. Instead of your app repeatedly asking "Is it ready yet?" (called polling), the other service simply notifies you the moment something happens.

Real-world analogy:

Imagine ordering food at a restaurant. Polling would be walking up to the kitchen every 30 seconds asking "Is my food ready?" — annoying and inefficient. A webhook is like the buzzer they give you that vibrates when your order is ready. You can relax until you're notified.

2How Webhooks Work

Here's the typical flow:

1

You register a webhook URL

You tell the service "When X happens, send an HTTP POST request to this URL: https://myapp.com/webhooks/transcript-ready"

2

The event happens

Something triggers the webhook — a transcript finishes processing, a payment completes, a user signs up, etc.

3

You receive a notification

The service sends a POST request to your URL with details about the event (usually as JSON). Your server receives this and can act on it immediately.

3Polling vs. Webhooks

Polling

  • ✗Constantly asking "Is it ready yet?"
  • ✗Wastes server resources and API calls
  • ✗Delays between checks mean slower response
  • ✗Can hit rate limits quickly

Webhooks

  • ✓Get notified instantly when events happen
  • ✓No wasted API calls or resources
  • ✓Real-time response to events
  • ✓More efficient and scalable

4Common Webhook Examples

You probably interact with webhooks daily without realizing it:

  • 💳
    Payment processors (Stripe, PayPal)

    Send a webhook when a payment succeeds, fails, or is refunded.

  • 📧
    Email services (SendGrid, Mailgun)

    Notify you when emails are delivered, opened, or bounced.

  • 🔔
    GitHub / GitLab

    Trigger CI/CD pipelines when code is pushed or PRs are merged.

  • 🎬
    VCA Transcript API

    Notifies your server when a transcript job completes or fails.

5What a Webhook Looks Like

When an event triggers a webhook, the sending service makes an HTTP POST request to your URL. Here's an example from our Transcript API:

POST https://yourapp.com/webhooks/transcript
Content-Type: application/json
X-Webhook-Signature: t=1704567890,v1=5257a869...

{
  "event": "job.completed",
  "jobId": "abc-123-def",
  "youtubeUrl": "https://youtu.be/dQw4w9WgXcQ",
  "status": "completed",
  "transcript": "Full transcript text...",
  "completedAt": "2026-03-21T04:15:00Z"
}

Your server receives this, verifies the signature, parses the JSON, and can immediately take action — like storing the transcript, sending a notification, or triggering another workflow.

6Security Considerations

Since anyone could theoretically send a POST request to your webhook URL, it's important to verify that incoming webhooks are legitimate:

  • 🔐Signature verification: Most services include a cryptographic signature in the headers that you can verify using a shared secret.
  • 🔐HTTPS only: Always use HTTPS for your webhook endpoints to encrypt data in transit.
  • 🔐Timestamp checks: Verify the webhook wasn't sent too long ago to prevent replay attacks.

Ready to set up webhooks?

Configure your webhook URL in the Dashboard to receive real-time notifications when your transcript jobs complete. No more polling!

Go to DashboardView Webhook API Docs