Webhooks

Events, not polling.

Klang pushes a signed HTTP request to your endpoint the moment something interesting happens. We retry with backoff for up to ~7 hours per event. See the event catalog for what you can subscribe to and verifying signatures for how to authenticate the deliveries.

Payload shape

Every event uses the same envelope. data contains the resource at the time of the event. No need to refetch unless you're pulling related objects.

{
  "id":         "evt_aB3xK7-pQrLm9wY8",
  "type":       "conversation.ready",
  "created_at": "2026-05-07T14:32:09Z",
  "data": {
    "id":         "kw3pq2nyax7lr9d",
    "title":      "Q2 roadmap planning",
    "started_at": "2026-05-07T13:00:00Z",
    "status":     "ready"
  }
}

Payloads are minimal by design. Webhooks tell you something happened and give you the id; GET /api/v1/conversations/{id} returns the full payload: summary, transcript, sources, participants, language, duration. This keeps the contract stable as the API evolves.

conversation.failed additionally includes an error_reason; conversation.deleted includes the last-known title so you can drop it from downstream caches.

Delivery & retries

We expect a 2xx response within 5 seconds. Anything else is a failure and triggers a retry.

Attempt 1

Immediately after the event fires.

Retries

Five retries with exponential backoff: 30s, 2m, 10m, 1h, then 6h.

Give up

After 6 attempts (~7 hours) the delivery is dropped. If your endpoint keeps failing for 24+ hours, we automatically pause it and email the creator.

Setting up a webhook

Open Settings → Developers → Webhooks, add your endpoint URL, and pick which events to subscribe to. Each webhook gets a signing secret. Copy it into your environment as KLANG_WEBHOOK_SECRET.

The same page shows the delivery log so you can see what's been sent, the response your server returned, and which deliveries failed.

Open webhook settings arrow_forward