Skip to main content
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

EventWhen it fires
conversion.startedA batch conversion or compression begins processing.
conversion.progressEach file in a batch finishes (progress updates).
conversion.completedAll files in a batch complete successfully.
conversion.failedA conversion or compression job fails.
file.uploadedAn original, uploaded, or converted file is stored.
media.tool.completedA media tool request completes (thumbnail, watermark, PDF preview, trim, GIF, etc.).
media.tool.failedA media tool request fails after authentication.
video.stream.startedAn HLS video stream asset starts processing.
video.stream.readyA video stream manifest, renditions, segments, and poster frame are ready for playback.
video.stream.failedA video stream asset fails during processing.
workflow.completedA workflow run completes and delivers its configured webhook step.

​
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": 1778320800,
  "data": {
    "jobId": "job_id",
    "filename": "output.webp"
  }
}

​
Signed headers

HeaderPurpose
convertly-eventThe event type being delivered.
convertly-timestampUnix timestamp used in the signature payload.
convertly-signatureHMAC signature in t={timestamp},v1={hash} format.

​
Delivery behavior

Convertly attempts delivery immediately, then retries after short backoff windows before marking a delivery as failed.

​
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 endpoint, event type, status, HTTP status, response body preview, attempt count, and timestamps. To replay a delivery, call: 
curl -X POST "https://convertly.sh/api/webhooks/deliveries/{deliveryId}/retry" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

Build with webhooks

Verify signatures and subscribe to Convertly events.