Webhooks - lyrcs.ai

Webhooks deliver event payloads to your server as jobs complete. Pass a webhook_url when submitting a job or batch — lyrcs.ai will POST the event payload to that URL.

Webhooks are the recommended way to consume the API. They fire only on terminal outcomes, so there is no in-flight state to interpret and no need to decide how long is too long. Polling works, but it puts the burden of judging “is this job stuck?” on your client — and that judgement is the single most common source of integration bugs.If you do poll, see job status for how long jobs legitimately take, and don’t impose a shorter timeout of your own.

Events

Event	Fired when
`job.complete`	Job finishes successfully (or after artist approval if `review=true`)
`job.awaiting_review`	Alignment done and `review=true` — results held pending artist approval
`job.degraded`	First upstream (Gemini 503) retry — job is still processing
`job.failed`	Job fails permanently
`batch.complete`	All jobs in a batch finish (whether complete or failed)

Retry schedule

lyrcs.ai retries failed webhook deliveries (non-2xx or timeout) on this schedule:

Attempt	Delay
1	Immediate
2	+1 minute
3	+5 minutes
4	+30 minutes

Your endpoint must return a 2xx response within 10 seconds or the delivery is counted as failed.

The job.complete webhook fired after artist approval in the review flow uses single-attempt delivery — it does not retry. Ensure your review webhook endpoint is reliable.

Signature verification

Every webhook delivery includes an X-Lyrcs-Signature header containing an HMAC-SHA256 signature of the request body, keyed with your webhook_secret. Verify the signature before processing the payload to confirm the request came from lyrcs.ai.

Node.js — signature verification

import crypto from "crypto";

export function verifyLyrcsSignature(rawBody, signature, webhookSecret) {
  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

// In your webhook handler (e.g. Express):
app.post("/webhooks/lyrcs", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-lyrcs-signature"];
  if (!verifyLyrcsSignature(req.body, signature, process.env.LYRCS_WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  // handle event...
  res.sendStatus(200);
});

Event payloads

job.complete

Fires when a job completes successfully. downloads is omitted when align=false was set. cultural_notes may be null.

{
  "event": "job.complete",
  "job_id": "a1b2c3d4-...",
  "external_id": "CATALOG_76007488",
  "created_at": "2024-01-01T00:00:00.000Z",
  "language": "Tamil",
  "duration_seconds": 214,
  "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
  "results": {
    "transcript": "நான் உன்னை நேசிக்கிறேன்...",
    "transliteration": "Naan unnai nesikirein...",
    "translation": "I love you...",
    "cultural_notes": null,
    "downloads": {
      "lrc_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/original",
      "lrc_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/transliterated",
      "srt_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/original",
      "srt_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/transliterated",
      "words_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/words/original",
      "words_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/words/transliterated"
    }
  },
  "second_opinion": {
    "total_lines": 59,
    "agreed_lines": 47,
    "match_ratio": 0.79,
    "suggestions": [],
    "hidden_count": 0
  },
  "alignment": {
    "method": "forced",
    "coverage": 0.998,
    "line_flags": []
  }
}

Download URLs in the payload still require your API key in the Authorization header to fetch.

words_original and words_transliterated are present when word_align_requested: true (the default). Jobs submitted with word_align=false include only lrc_* and srt_* in downloads.

second_opinion and alignment are always present and may be null, which means the check did not run. An empty suggestions array is the opposite signal — it ran and agreed with every line. See Quality Signals.

job.awaiting_review

Fires instead of job.complete when review=true and alignment succeeded. No results block — lyrics are held until the artist approves.

{
  "event": "job.awaiting_review",
  "job_id": "a1b2c3d4-...",
  "language": "Punjabi",
  "review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=abc123",
  "expires_at": "2024-01-02T00:00:00.000Z",
  "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-..."
}

Forward review_url to the artist. When they approve, job.complete fires with the full payload.

job.degraded

Fires on the first Gemini 503 retry only. The job is still processing — this is informational. Do not assume the job has failed.

{
  "event": "job.degraded",
  "job_id": "a1b2c3d4-...",
  "language": "Hindi",
  "reason": "gemini_503",
  "attempt": 1,
  "retrying_in_ms": 7243,
  "message": "Transcription delayed due to upstream capacity. Job is retrying automatically."
}

Field	Value
`reason`	Always `"gemini_503"`
`attempt`	Always `1` — only fires on the first retry
`retrying_in_ms`	Milliseconds until the retry fires (includes jitter)

job.failed

Fires when a job fails permanently after all retries are exhausted.

{
  "event": "job.failed",
  "job_id": "a1b2c3d4-...",
  "created_at": "2024-01-01T00:00:00.000Z",
  "language": "Tamil",
  "error": "processing_failed"
}

batch.complete

Fires when all jobs in a batch have finished — whether complete or failed. status is "complete" if all jobs succeeded, "partial" if any failed or timed out. downloads is included per job only when status === "complete" AND align_requested === true for that job.

{
  "event": "batch.complete",
  "batch_id": "b1a2t3c4-...",
  "status": "partial",
  "job_count": 3,
  "completed": 2,
  "failed": 1,
  "jobs": [
    {
      "job_id": "a1b2c3d4-...",
      "external_id": "TRACK_001",
      "language": "Hindi",
      "status": "complete",
      "review_required": false,
      "review_url": null,
      "review_approved_at": null,
      "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
      "downloads": {
        "lrc_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/original",
        "lrc_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/transliterated",
        "srt_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/original",
        "srt_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/transliterated"
      }
    },
    {
      "job_id": "b2c3d4e5-...",
      "external_id": "TRACK_002",
      "language": "Tamil",
      "status": "failed",
      "review_required": false,
      "review_url": null,
      "review_approved_at": null,
      "studio_url": "https://lyrcs.ai/studio/b2c3d4e5-..."
    }
  ]
}

​Events

​Retry schedule

​Signature verification

​Event payloads

​job.complete

​job.awaiting_review

​job.degraded

​job.failed

​batch.complete

Events

Retry schedule

Signature verification

Event payloads

job.complete

job.awaiting_review

job.degraded

job.failed

batch.complete