Setting up webhooks

Webhooks let you receive notifications when conversions complete, instead of polling the API.

Setup

1. Go to your Webhooks dashboard.
2. Click “Add Webhook URL”.
3. Enter your endpoint URL (must be HTTPS).
4. Copy the signing secret — you’ll need it to verify payloads.

Webhook events

Verifying signatures

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Verify it to ensure the request came from KoalaPic:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry policy

Failed deliveries (non-2xx responses) are retried up to 3 times with increasing delays: immediately, after 30 seconds, and after 2 minutes. After 3 failures, the delivery is marked as failed and visible in your dashboard.

Per-request webhooks

You can also set a webhook URL per conversion request by including webhook_url in your API call. This overrides your default webhook for that specific conversion.