Webhooks

Webhooks let your product react when Convertly finishes work. Instead of polling every possible workflow forever, you can subscribe to events and update your own records when a conversion or file upload completes.

Subscribable events

Event	When it fires
`conversion.started`	A batch conversion or compression begins processing.
`conversion.progress`	Each file in a batch finishes (progress updates).
`conversion.completed`	All files in a batch complete successfully.
`conversion.failed`	A conversion or compression job fails.
`compression.started`	A batch compression begins processing.
`compression.progress`	Each file in a compression batch finishes.
`compression.completed`	All files in a compression batch complete successfully.
`compression.failed`	A compression job fails.
`file.uploaded`	An original, uploaded, or converted file is stored.
`file.created`	Any workspace library asset is created, including API, AI, workflow, restore, and WordPress writes.
`file.updated`	A workspace library asset changes.
`file.deleted`	A workspace library asset is removed.
`ai.transform.started`	A Forma AI image transform begins processing.
`ai.transform.completed`	A Forma AI image transform produces a stored output.
`ai.transform.failed`	A Forma AI image transform reaches a terminal failure.
`recovery.created`	A recovery point is validated and ready.
`recovery.restored`	Files are restored from a recovery point or legacy recovery archive.
`media.tool.started`	An asynchronous media tool request begins processing.
`media.tool.completed`	A media tool request completes (thumbnail, watermark, PDF preview, trim, GIF, etc.).
`media.tool.failed`	A media tool request fails after authentication.
`video.stream.started`	An HLS video stream asset starts processing.
`video.stream.ready`	A video stream manifest, renditions, segments, and poster frame are ready for playback.
`video.stream.failed`	A video stream asset fails during processing.
`workflow.started`	A live workflow run begins processing.
`workflow.completed`	A workflow run completes successfully.
`workflow.partial`	A workflow finishes with skipped or partial steps.
`workflow.failed`	A workflow run fails.

Event delivery

Convertly posts a JSON event envelope to each active endpoint subscribed to the event type. Every delivery includes the event type, timestamp, and HMAC signature headers.

{
  "id": "evt_2d44218f-1a79-46af-b6a8-34a0c50f1e8d",
  "type": "conversion.completed",
  "created": 1785240000,
  "created_at": "2026-07-28T12:00:00.000Z",
  "data": {
    "jobId": "job_id",
    "filename": "output.webp"
  }
}

Signed headers

Header	Purpose
`convertly-event`	The event type being delivered.
`convertly-event-id`	Stable event identifier. It does not change between retry attempts or manual replay.
`convertly-timestamp`	Unix timestamp used in the signature payload.
`convertly-signature`	HMAC signature in `t={timestamp},v1={hash}` format.

Delivery behavior

Convertly accepts events durably and delivers them asynchronously, so a slow customer endpoint does not hold the originating API request open. Failed deliveries retry after approximately 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours, and 72 hours. After the eighth failed attempt the delivery enters dead_letter. Five consecutive dead-letter deliveries automatically pause the endpoint; an owner or admin can review the failure and explicitly enable it again. Interrupted delivery attempts are recovered automatically. Consumers should still store convertly-event-id and make handlers idempotent because networks can deliver the same event more than once.

Delivery history and retries

Use delivery history to show webhook health in your dashboard or support tools:

curl "https://convertly.sh/api/webhooks/deliveries?limit=25" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

Each delivery includes the stable event ID, endpoint, event type, status, HTTP status, response body preview, attempt count, next retry, replay count, last error, and timestamps. To replay a delivery, call:

curl -X POST "https://convertly.sh/api/webhooks/deliveries/{deliveryId}/retry" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

The replay keeps the original event ID and queues the existing outbox record again. Restricted API keys need the webhooks:manage scope.

Build with webhooks

Verify signatures and subscribe to Convertly events.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Subscribable events

Event delivery

Signed headers

Delivery behavior

Delivery history and retries

Build with webhooks

​Subscribable events

​Event delivery

​Signed headers

​Delivery behavior

​Delivery history and retries

Build with webhooks

Subscribable events

Event delivery

Signed headers

Delivery behavior

Delivery history and retries