Webhooks

Every state change is delivered as a signed HTTPS POST. Handlers must verify the signature, ack fast, and process asynchronously.

Updated Jul 15, 2026API 2026-07-01 Edit on GitHub Report an issue

Event delivery

Events are POSTed to the endpoint you registered with an HMAC-SHA256 signature in Korven-Signature. Delivery is at-least-once, so handlers must be idempotent on event.id.

Verifying signatures

SDK v1.0.0

import crypto from "node:crypto";
export function verify(rawBody: string, header: string, secret: string) {
  const [tsPart, sigPart] = header.split(",");
  const ts = tsPart.split("=")[1];
  const sig = sigPart.split("=")[1];
  const payload = `${ts}.${rawBody}`;
  const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
  const fresh = Math.abs(Date.now()/1000 - Number(ts)) < 300;
  if (!ok || !fresh) throw new Error("invalid signature");
  return JSON.parse(rawBody);
}

Retries & replay

Non-2xx responses are retried with exponential backoff for 72 hours.
The dashboard lets you replay any event delivery.
Handlers should acknowledge within 5 seconds, then process in a background worker.

Local development

API v1

korven listen --forward-to http://localhost:3000/webhooks/korven

The korven listen CLI streams live sandbox events to your localhost without exposing a public URL.

Pagination

SDKs