Webhooks

Receive real-time notifications when async jobs complete

How It Works

When submitting an async TTS job, pass a webhook_url in the request body. Once the job reaches a terminal state (completed or failed), Vrex sends a POST request to that URL with a JSON payload. Your endpoint must respond with a 2xx status code to acknowledge receipt.

Event Types

Event	Description
job.completed	Fired when async TTS generation finishes successfully.
job.failed	Fired when generation fails after all retries are exhausted.

Payload

{
  "event": "job.completed",
  "job_id": "abc123",
  "generation_id": "gen_456",
  "status": "completed",
  "audio_url": "https://cdn.getvrex.com/audio/gen_456.mp3",
  "chars": 1500,
  "duration_ms": 12000,
  "timestamp": "2026-01-15T10:30:15Z"
}

Signature Verification

Coming soon. Currently webhook payloads are unsigned. Use HTTPS endpoints and validate the job_id against your own records to confirm authenticity.

Retry Policy

Vrex fires each webhook once. If your endpoint returns a non-2xx response, no automatic retries are attempted. Ensure your handler is idempotent and responds within 5 seconds to avoid timeouts.

Handler Example

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/vrex", (req, res) => {
  const { event, job_id, status, audio_url } = req.body;

  // Validate job_id against your own records
  if (event === "job.completed") {
    console.log(`Job ${job_id} done — audio: ${audio_url}`);
  } else if (event === "job.failed") {
    console.error(`Job ${job_id} failed`);
  }

  res.sendStatus(200); // must return 2xx
});