Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks are configured from the dashboard. Convertly sends JSON payloads to active endpoints whose event_types include the event, so your application can update records or notify users without polling every workflow.
Store the whsec_ secret when you create a webhook. Convertly uses it to sign each delivery.

​
What webhooks are for

Use webhooks to mark a user upload as ready, attach converted files to your own records, send a notification, continue an automation, or record currency conversion activity after Convertly finishes the work.

​
Event envelope

{
  "id": "evt_2d44218f-1a79-46af-b6a8-34a0c50f1e8d",
  "type": "conversion.completed",
  "created": 1778320800,
  "data": {
    "jobId": "job_id",
    "filename": "output.webp"
  }
}

​
Delivery headers

HeaderDescription
user-agentConvertly-Webhooks/1.0
convertly-eventEvent type.
convertly-timestampUnix timestamp used for signing.
convertly-signaturet={timestamp},v1={hmac}

​
Verify signatures

The signature is an HMAC-SHA256 over {timestamp}.{rawBody} using the webhook secret. 
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyConvertlyWebhook(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const payload = `${parts.t}.${rawBody}`;
  const expected = createHmac("sha256", secret).update(payload).digest("hex");

  return timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

​
Subscribable events

EventWhen it fires
conversion.startedA batch conversion begins processing.
conversion.progressA file in a batch is processed.
conversion.completedA conversion or compression completes.
conversion.failedA conversion job fails.
file.uploadedAn original or converted file is stored.
currency.conversion.completedAn authenticated currency conversion completes.
Convertly attempts delivery immediately, then retries after roughly 5 seconds and 25 seconds before marking a delivery failed.