Webhooks

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, or continue an automation after Convertly finishes the work.

Event envelope

{
  "id": "evt_2d44218f-1a79-46af-b6a8-34a0c50f1e8d",
  "type": "conversion.completed",
  "created": 1778320800,
  "created_at": "2026-05-09T10:00:00.000Z",
  "data": {
    "jobId": "job_id",
    "filename": "output.webp"
  }
}

Delivery headers

Header	Description
`user-agent`	`Convertly-Webhooks/1.0`
`convertly-event`	Event type.
`convertly-event-id`	Stable identifier to use as your idempotency key, including on replay.
`convertly-timestamp`	Unix timestamp used for signing.
`convertly-signature`	`t={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

Event	When it fires
`conversion.completed`	A conversion or compression completes.
`file.uploaded`	An original, uploaded, or converted file is stored.
`file.created`, `file.updated`, `file.deleted`	A workspace library asset is created, changed, or deleted.
`ai.transform.started`, `ai.transform.completed`, `ai.transform.failed`	A Forma AI transform changes state.
`recovery.created`, `recovery.restored`	A validated recovery point is created or restored.
`media.tool.completed`	A media tool request completes, such as a thumbnail, watermark, PDF preview, audio extraction, metadata tool, or inspection.
`workflow.completed`	A workflow run completes and delivers its configured webhook step.

Convertly stores events before delivery and sends them asynchronously. Failed deliveries retry with exponential backoff for up to roughly seven days. A delivery that exhausts its attempts moves to the dead-letter state and can be replayed from Settings. After five consecutive dead-letter deliveries, Convertly automatically pauses the endpoint to protect both systems. Return any 2xx response promptly, verify signatures against the raw request body, and store convertly-event-id before applying side effects. Delivery is at least once, so consumers must be idempotent.

Build Flows

Image CDN

AI Agents

What webhooks are for

Event envelope

Delivery headers

Verify signatures

Subscribable events

​What webhooks are for

​Event envelope

​Delivery headers

​Verify signatures

​Subscribable events

What webhooks are for

Event envelope

Delivery headers

Verify signatures

Subscribable events