Webhooks

Overview

kurnl sends HTTP POST requests to your webhook_url after significant events. The webhook_url lives on your provider integration settings (tenant-config); the signing secret is the Shared webhook secret from the dashboard Checkout page.

Webhooks are inert until webhook_url is configured — events are silently skipped, with no error. And if no webhook secret is set, deliveries arrive unsigned (no X-Webhook-Signature header): configure a secret and reject unsigned requests.

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`	A line goes live: CKO-03 direct/anonymous provisioning, CKO-04/bulk, a provider switch, and the install paths (home-drop, confirm-install, a pre-order going live). It also fires when kurnl brings a line back (`kind: "reactivated"`). For a first-line order on a shared suite it fires when the operator confirms the connection, not when the order is placed	`subscription_id`, `kind` (`first` or `reactivated`), `activated_at`, `plan_version_id`, `location_hash` where the line has one; `subscriber_id` only on a partner order with a named customer (`external-checkout/complete`, `provisioning/provider-initiated`, `provisioning/bulk`, and a shared-suite order when the operator confirms it) — not on the install paths, a provider switch or a reactivation
`install.booked`	A technician visit is booked or moved: the customer picks a window, rebooks it, your staff book it for them in the dashboard, or kurnl staff book it	`subscription_id`, `appointment_start`, `appointment_end` (ISO 8601 with offset), `booked_by` (`customer`, `provider` when your staff booked it in the dashboard, or `staff` for kurnl), `rebooked` (`true` when a booked visit was moved)
`subscription.pending_install`	Install-path signup received — install not yet done	named: `subscription_id`, `subscriber_id`, `plan_version_id`, `unit_id`, `delivery_mode`; anonymous: no `subscriber_id`
`subscription.cancelled`	Subscription cancelled (dashboard cancel, your own `cancel` call, or provider switch)	`subscription_id`, `canceled_at`, `ended_at`, `cancellation_reason` — the provider-switch variant sends only `subscription_id`, `ended_at`, `cancellation_reason: "provider_switch"` (no `canceled_at`)
`subscription.deprovisioned`	Line closed after its cancellation: the port is reset/released, except for a line that was never installed whose port kurnl never provisioned	`subscription_id`, `deprovisioned_at`
`provisioning.completed`	SSH port provisioning finished successfully	`job_id`, `subscription_id`
`provisioning.failed`	SSH provisioning failed	`job_id`, `subscription_id`, `error`

On every event: subscription_id, external_subscription_id (your own identifier; null when the line has none) and is_anonymous. They are additive: nothing you already read has moved.What is not emitted: there is no subscription.suspended event, and a restore you request through the status call sends no new subscription.activated event. Also mind the payload variants: subscription.activated from a provider switch carries kind, activated_at and plan_version_id like every activation, plus started_at and via: "provider_switch", but no location_hash or subscriber_id, so don’t key on those unconditionally.

subscription.activated used to be silent on the home-drop and confirm-install paths. It now fires there too, with kind: "first". A line you cancelled and kurnl later brings back sends it again with kind: "reactivated". An example of the new visit event:

{
  "event": "install.booked",
  "provider_document_id": "a1b2c3d4-...",
  "timestamp": 1714000000.123,
  "subscription_id": "8c4a1b9e-...",
  "external_subscription_id": "your-internal-id-123",
  "is_anonymous": true,
  "appointment_start": "2026-11-03T09:00:00-05:00",
  "appointment_end": "2026-11-03T11:00:00-05:00",
  "booked_by": "customer",
  "rebooked": false
}

Backup e-mail for anonymous lines

For an anonymous line, kurnl can also send every one of these events to an e-mail address of your choice, next to the webhook. It is a safety net, for the day your endpoint is down or a delivery is dropped. Set the address under Backup notification e-mail on the dashboard Checkout page; the Send notification e-mails switch turns it off. It works without a webhook_url too. The mails come from kurnl’s status address. Lines of named subscribers send no backup mail, and neither do port offline or port restored.

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 first attempts delivery up to 3 times inline, with exponential back-off (2s, then up to 30s between retries) and a 15 second timeout per attempt
If all inline attempts fail, the event moves to a dead-letter queue: a scheduler (every 10 minutes) redelivers it with growing back-off until 5 total attempts have been made, then the event is dropped and kurnl operations is alerted
Every delivery carries an X-Webhook-Event header with the event name; DLQ redeliveries additionally carry X-Webhook-Retry: true — use it for dedup awareness
Network errors and 5xx responses are retried; 4xx responses are not retried (a 4xx during DLQ redelivery ends retrying immediately)
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 (POST /api/v1/sandbox/webhook-config):
# 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

The sandbox has its own webhook event feed — but it is a different pipeline with different event names than the production events on this page. See Sandbox for how to configure, list, and replay sandbox webhook events. For production issues, remember the delivery behaviour above: failed events are redelivered from the dead-letter queue with X-Webhook-Retry: true, and events that exhaust all attempts alert kurnl operations.

Getting Started

Provider Guides

Operator Guides

Partner Integration

AI Support Agent

Changelog

Overview

Event reference

Backup e-mail for anonymous lines

Payload structure

Verifying signatures

Delivery behaviour

Idempotency

Testing webhooks locally

Debugging delivery failures

​Overview

​Event reference

​Backup e-mail for anonymous lines

​Payload structure

​Verifying signatures

​Delivery behaviour

​Idempotency

​Testing webhooks locally

​Debugging delivery failures

Overview

Event reference

Backup e-mail for anonymous lines

Payload structure

Verifying signatures

Delivery behaviour

Idempotency

Testing webhooks locally

Debugging delivery failures