Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karta.sh/llms.txt

Use this file to discover all available pages before exploring further.

Karta can POST event notifications to an HTTPS endpoint you own — subscription changes, budget thresholds, and other org events — so your systems react without polling.

​
Register an endpoint

import { Karta } from "@karta/sdk";
const karta = new Karta({ apiKey: process.env.KARTA_API_KEY! });

const { webhook_endpoint, secret } = await karta.webhookEndpoints.create({
  url: "https://example.com/karta-webhook",
  event_types: ["subscription.created", "invoice.paid"],
});
// `secret` (whsec_…) is shown once — use it to verify signatures.

await karta.webhookEndpoints.list();
await karta.webhookEndpoints.update(id, { event_types: [...] });
await karta.webhookEndpoints.delete(id);
Each endpoint subscribes to a selected set of event types — you receive only what you ask for.

​
Verifying signatures

Deliveries are signed HMAC-SHA256 in a Stripe-compatible format. Compute the expected signature over the raw request body with your endpoint’s signing secret and compare in constant time before trusting the payload. 
import hmac, hashlib

def verify(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
Always verify against the raw request body, before any JSON parsing or re-serialization — reserializing changes the bytes and breaks the signature.

​
Delivery, retries, and auto-disable

  • Delivery uses retry with exponential backoff.
  • An endpoint that keeps failing (~25 consecutive failures) is auto-disabled; an admin can re-enable it.

​
SSRF protection

The delivery path judges twice. At write time, the URL must be HTTPS with no private hosts or IP literals. At delivery time, Karta re-resolves DNS and pins the socket to the resolved IP — defeating DNS-rebinding between validation and connect. You can’t point a webhook at internal infrastructure.
Webhooks are outbound notifications from Karta to you. They’re distinct from the gateway, which fans messages out to session participants.