Event guide

Build a signed webhook receiver for video encoding events

Receive signed Convertrilo job events, verify the HMAC signature, and update your own product when outputs are ready.

Webhooks turn long-running encoding work into product events. Your app can publish assets, notify users, run follow-up automation, or mark a job failed without running its own polling loop.

Create API keyAPI docsIntegration overview
Verify a webhookguide
const signature = req.headers["x-convertrilo-signature"];
const rawBody = await req.text();

const expected = crypto
  .createHmac("sha256", process.env.CONVERTRILO_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (signature !== expected) {
  return new Response("Invalid signature", { status: 401 });
}

const event = JSON.parse(rawBody);

Create a webhook endpoint from Developer Settings.

Store the one-time signing secret in your backend secret manager.

Keep access to the raw request body for signature verification.

Make event handling idempotent in your own database.

Recipe

Build the workflow with stable API primitives

These guides focus on primitives that can be reused by dashboards, queue workers, scripts, CLIs, MCP tools, and agent runtimes.

  1. Step 1

    Verify the HMAC signature before trusting the payload.

  2. Step 2

    Read the job id, event type, externalId, metadata, and output details.

  3. Step 3

    Update your asset, lesson, campaign, or upload record exactly once.

  4. Step 4

    Return a 2xx response only after your receiver has accepted the event.

Publish gates

Keep user-facing content hidden until a job.completed event confirms the output upload has finished.

Delivery history

Use webhook delivery records to debug failed receivers, status codes, response bodies, and retry scheduling.

Agent handoff

Webhook events can trigger downstream agents or workflow tools after the expensive media work is complete.

Developer questions

Can I test a webhook before real jobs finish?

Yes. Developer Settings includes webhook test delivery so you can verify routing, signatures, and response handling.

What should my receiver return?

Return a 2xx response after accepting the event. Non-2xx responses are treated as failed deliveries and can be retried.

Should webhook handlers start another encode immediately?

They can, but keep chained jobs idempotent so retries or duplicate deliveries do not create duplicate paid work.

Related developer paths

SDK quickstartInstall the Convertrilo TypeScript SDK, create an API key, submit a retry-safe encoding job, and wait for a completed output.Queue automationConnect Convertrilo to your own queues, cron jobs, imports, and backfills without duplicating jobs when retries happen.S3 output workflowsRoute completed video encodes to S3-compatible buckets so your product keeps ownership of storage, CDN, lifecycle rules, and access control.MCP setupInstall @convertrilo/sdk, save an API key with the CLI, configure convertrilo-mcp in an MCP client, and verify the available video encoding tools.Agent workflowsDesign agent-friendly video encoding workflows with the Convertrilo MCP server, scoped API keys, deterministic job payloads, idempotency, polling, and signed webhooks.Video encoding APICreate video encoding jobs from your backend with API keys, idempotency, metadata, priority queues, webhooks, and storage destinations you control.Video encoding CLIAutomate video compression from terminals, deployment jobs, content pipelines, and scheduled scripts with a Convertrilo CLI workflow.VMAF video encodingUse VMAF-guided sample encoding to choose a better quality target before the final video encode, without manually testing bitrate settings.Two-pass video encodingUse classic two-pass H.264 and H.265 encoding when predictable bitrate allocation matters more than raw hardware speed.

Start with a real estimate

Choose your codec, resolution, FPS, bitrate, quality, and optimization settings. Convertrilo shows the NEU estimate before credits are reserved, and failed jobs release reserved credits back to your balance.

Start FreeCalculate Pricing