Skip to main content

Webhooks

Webhooks allow you to receive prediction results automatically without polling.

Configuring Webhooks​

Include webhook parameters in your prediction request:

response = requests.post(
    f"{API_URL}/projects/{PROJECT_ID}/predict",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "input": data,
        "webhookUrl": "https://your-server.com/predictions/callback",
        "webhookSecret": "your_secret_key"
    }
)

Webhook Payload​

When the prediction completes, Kanva sends a POST request to your webhook URL:

{
  "jobId": "abc123",
  "projectId": "your-project-id",
  "status": "completed",
  "result": {
    "predictions": ["value"],
    "probabilities": [0.9, 0.1]
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Signature Verification​

If you provide a webhookSecret, Kanva signs the payload using HMAC-SHA256. Verify the signature to ensure the request is authentic:

import hmac
import hashlib

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

# In your webhook handler
signature = request.headers.get("X-Kanva-Signature")
if not verify_signature(request.body, signature, WEBHOOK_SECRET):
    return HttpResponse(status=401)

Retry Behavior​

If your webhook endpoint returns an error (5xx) or times out:

  • Kanva retries up to 3 times
  • Retry intervals: 30 seconds, 2 minutes, 10 minutes
  • After all retries fail, the job is marked as delivered but webhook failed

Testing Locally​

Use tools like ngrok to test webhooks during development:

ngrok http 8000
# Use the generated HTTPS URL as your webhookUrl