Webhooks

Overview

kurnl sends HTTP POST requests to your webhook_url after significant events. Configure your webhook URL in Dashboard → Settings → Integration. All events share a common envelope structure with event-specific fields merged in at the top level.

Event reference

Event	When fired	Key fields
`subscription.activated`	Subscription becomes ACTIVE	`subscription_id`, `subscriber_id`, `plan_version_id`, `location_hash`
`subscription.pending_install`	Home-drop signup received — install not yet done	`subscription_id`, `subscriber_id`, `unit_id`
`subscription.cancelled`	Subscription cancelled from any source	`subscription_id`
`subscription.suspended`	Subscription paused (e.g. non-payment)	`subscription_id`
`subscription.deprovisioned`	Port reset/released after teardown	`subscription_id`
`provisioning.completed`	SSH port provisioning finished successfully	`job_id`, `subscription_id`
`provisioning.failed`	SSH provisioning failed after all retries	`job_id`, `subscription_id`, `error`

Payload structure

{
  "event": "provisioning.completed",
  "provider_document_id": "a1b2c3d4-...",
  "timestamp": 1714000000.123,
  "job_id": "3d6e8f12-...",
  "subscription_id": "8c4a1b9e-..."
}

All payloads include event, provider_document_id, and timestamp. Event-specific fields are merged in alongside them.

Verifying signatures

When you have a webhook_secret configured, kurnl signs every request body with HMAC-SHA256 and sends the signature in the X-Webhook-Signature header as sha256=<hex_digest>. Always verify this signature before processing any event.

import hashlib
import hmac

def verify_kurnl_webhook(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

# In your handler:
sig = request.headers.get("X-Webhook-Signature", "")
if not verify_kurnl_webhook(request.body, sig, KURNL_WEBHOOK_SECRET):
    return Response(status_code=401)

const crypto = require('crypto');

function verifyKurnlWebhook(body, header, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header)
  );
}

// In your handler:
const sig = req.headers['x-webhook-signature'] || '';
if (!verifyKurnlWebhook(req.rawBody, sig, process.env.KURNL_WEBHOOK_SECRET)) {
  return res.status(401).send('Invalid signature');
}

function verifyKurnlWebhook(string $body, string $header, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
    return hash_equals($expected, $header);
}

// In your handler:
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (!verifyKurnlWebhook(file_get_contents('php://input'), $sig, getenv('KURNL_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}

Delivery behaviour

kurnl attempts delivery up to 3 times with exponential back-off (2s, then up to 30s between retries)
Network errors and 5xx responses are retried; 4xx responses are not retried
Timeout per attempt: 15 seconds
Return any 2xx status to acknowledge — kurnl does not inspect the response body

Idempotency

kurnl may deliver the same event more than once after transient failures. Use job_id or subscription_id as an idempotency key to deduplicate in your handler:

def handle_provisioning_completed(event: dict):
    job_id = event["job_id"]
    if already_processed(job_id):
        return  # skip duplicate
    mark_processed(job_id)
    # ... your logic

Testing webhooks locally

During development you can use a tunnelling tool to expose your local server to kurnl:

# Using ngrok:
ngrok http 8000
# → Forwarding: https://abc123.ngrok.io → localhost:8000

# Set this as your sandbox webhook URL in the dashboard:
# https://abc123.ngrok.io/webhooks/kurnl

Alternatively, use webhook.site for a no-setup temporary receiver to inspect payloads without running any code.

Debugging delivery failures

In the dashboard under Documentation → Testing & Sandbox, you can see the last 50 webhook delivery attempts for your sandbox, including the response status and body. Failed events can be replayed from the dashboard. For production webhook issues, check Dashboard → Settings → Integration → Webhook Events.

Getting Started

Operator Guides

Integration Guides

AI Support Agent

Overview

Event reference

Payload structure

Verifying signatures

Delivery behaviour

Idempotency

Testing webhooks locally

Debugging delivery failures

​Overview

​Event reference

​Payload structure

​Verifying signatures

​Delivery behaviour

​Idempotency

​Testing webhooks locally

​Debugging delivery failures

Overview

Event reference

Payload structure

Verifying signatures

Delivery behaviour

Idempotency

Testing webhooks locally

Debugging delivery failures