> ## 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

> How Convertly sends signed events after conversions and uploads.

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.                                                  |
| `file.uploaded`        | An original, uploaded, or converted file is stored.                                     |
| `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.completed`   | A 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.

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

## Signed headers

| Header                | Purpose                                             |
| --------------------- | --------------------------------------------------- |
| `convertly-event`     | The event type being delivered.                     |
| `convertly-timestamp` | Unix timestamp used in the signature payload.       |
| `convertly-signature` | HMAC 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:

```bash theme={"system"}
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:

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

<Card title="Build with webhooks" icon="link" href="/guides/webhooks">
  Verify signatures and subscribe to Convertly events.
</Card>