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 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, file upload, or currency conversion completes.

​
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 conversion events.