Setting Up Image Conversion Webhooks

Image conversion isn’t instant — large files, batch jobs, and complex transformations take time. Instead of polling the API repeatedly, you can set up webhooks to get notified the moment a conversion completes (or fails).

How Webhooks Work

1. You register a webhook URL in your dashboard
2. You submit a conversion via the API
3. KoalaPic processes the image
4. When done, KoalaPic sends a POST request to your URL with the result

No polling. No wasted API calls. Your server gets notified exactly when the result is ready.

Setting Up Your Endpoint

Your webhook endpoint needs to: - Accept POST requests - Return a 2xx status code within 10 seconds - Handle JSON payloads

Here’s a minimal Flask receiver:

import hashlib
import hmac
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_webhook_secret"

@app.route("/webhooks/koalapic", methods=["POST"])
def handle_webhook():
    # Verify the signature
    signature = request.headers.get("X-KoalaPic-Signature")
    payload = request.get_data()
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "Invalid signature"}), 401

    data = request.json
    event = data["event"]

    if event == "conversion.completed":
        download_url = data["data"]["download_url"]
        print(f"Conversion done! Download: {download_url}")
    elif event == "conversion.failed":
        error = data["data"]["error"]
        print(f"Conversion failed: {error}")

    return jsonify({"received": True}), 200

HMAC Verification

Every webhook request includes an X-KoalaPic-Signature header — an HMAC-SHA256 hash of the request body signed with your webhook secret. Always verify this signature to ensure the request genuinely came from KoalaPic.

Your webhook secret is shown when you create an API key and is available in your dashboard.

Webhook Events

Retry Behavior

If your endpoint returns a non-2xx status or times out, KoalaPic retries up to 3 times with exponential backoff:

• Retry 1: After 30 seconds
• Retry 2: After 2 minutes
• Retry 3: After 10 minutes

After 3 failures, the webhook is marked as failed. You can view delivery history in your dashboard.

Per-Request Webhook URLs

Don’t want to use a global webhook? Pass a webhook_url parameter with any conversion request to receive the callback at a specific URL:

curl -X POST https://koalapic.com/api/v1/convert \
  -H "Authorization: Bearer kp_your_api_key" \
  -F "file=@photo.png" \
  -F "output_format=webp" \
  -F "webhook_url=https://your-app.com/hooks/conversion-123"

Testing Webhooks

Use a service like webhook.site or ngrok to expose a local endpoint for testing. Or use the webhook test button in your dashboard to send a sample payload to your endpoint.

Next Steps

• Configure webhooks in your dashboard
• Read the full webhook documentation
• Learn about real-time progress with SSE as an alternative