Webhooks

Webhooks let you skip polling: register a URL and ConvertMePls will POST to it when a conversion job changes state.

#Register an endpoint

Add a webhook in your dashboard, or via the API. You will receive a signing secret used to verify deliveries.

#The payload

We send a JSON body:

{
  "event": "conversion.completed",
  "jobId": "8f2b1c9a...",
  "status": "done",
  "downloadUrl": "https://...",
  "createdAt": "2026-06-01T12:00:00.000Z"
}

Events: conversion.completed and conversion.failed.

#Verify the signature

Each request includes an X-ConvertMePls-Signature header — an HMAC-SHA256 of the raw body using your signing secret. Recompute it and compare:

import crypto from 'node:crypto';

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

#Retries

If your endpoint does not return a 2xx, we retry with exponential backoff for up to 24 hours. Use the Test button in the dashboard to send a sample delivery while you build your handler.