Webhooks

Webhooks

Receive AI events at your own HTTPS endpoints — signed, retried, at-least-once.

Instead of polling, register an HTTPS URL and Krallo will POST a signed JSON event to it whenever something you subscribed to happens — for example when an image-generation job finishes. Every delivery carries an HMAC-SHA256 signature, is attempted at least once with automatic retries, and — if your endpoint stays unreachable — is parked in a dead-letter state you can replay from the console or the deliveries API.

How delivery works

Krallo uses a durable transactional-outbox pipeline, so a webhook can never break the operation that produced it:

1. A domain event (e.g. an imagine job completing) writes one frozen event row. The signed body is fixed at this moment and never re-serialized.
2. A background sweeper fans out each event to every active endpoint subscribed to it, creating one delivery per (event × endpoint).
3. The sweeper claims due deliveries under a short lease and POSTs each through an SSRF-guarded, IP-pinned sender. Deliveries to the same endpoint are serialized; different endpoints run in parallel.
4. A 2xx marks the delivery delivered. Anything else is retried with exponential backoff until it succeeds or exhausts its attempts, at which point it is dead-lettered.

Because fan-out and retries are decoupled from the source event, delivery is at-least-once: your endpoint may occasionally receive the same event more than once. Deduplicate on the X-Krallo-Event-Id header (see Idempotency and ordering).

Register an endpoint

Create an endpoint on your app in the console, or from the cookie-authenticated portal API. The URL is SSRF-validated before anything is stored, and a signing secret is minted and returned exactly once.

Body parameters (JSON, cookie session + CSRF token required):

URL requirements

The URL guard rejects anything that isn't a safe public target. A blocked URL returns 422 url_blocked with a message:

A successful create returns 201 with the endpoint and its one-time signing secret:

{
  "ok": true,
  "endpoint": {
    "id": "01JBK7Q2W8Z0M4X6R9V3T5N1D7",
    "appId": "01JBK6...",
    "url": "https://example.com/krallo/webhooks",
    "status": "unverified",
    "secretPrefix": "whsec_1a2b3c4d",
    "apiVersion": "v1",
    "verifiedAt": null,
    "consecutiveFails": 0,
    "subscriptions": []
  },
  "secret": "whsec_kQ8f...redacted...9pZ2"
}

Verify endpoint ownership

An endpoint is created unverified and receives no deliveries until it passes an ownership-and-reachability handshake. This proves you control the URL — not just that it looks public.

Immediately after creation (and on demand via POST /api/developer/webhooks/ping), Krallo sends a signed challenge to your URL:

POST https://example.com/krallo/webhooks
Content-Type: application/json
X-Krallo-Event: endpoint.verification
X-Krallo-Signature: t=1720000000,v1=<hmac-sha256-hex>

{"type":"endpoint.verification","challenge":"9f3c1a7b0e5d4a28c6f1b0..."}

There are two ways to complete verification:

• Echo the challenge (automatic). Respond 200 and include the challenge value somewhere in your response body. Krallo detects the echo and flips the endpoint to active with no further action.
• Submit the challenge. Capture the challenge value your server received and confirm it in the console, or POST it back:

  POST /api/developer/webhooks/verify
  Content-Type: application/json
  
  { "id": "01JBK7Q2...", "challenge": "9f3c1a7b0e5d4a28c6f1b0...", "csrf": "<token>" }

  A matching challenge (compared in constant time) returns 200 {"ok":true} and activates the endpoint; a mismatch returns 400 verification_failed.

Subscribe to events

A verified endpoint still receives nothing until you subscribe it to one or more event types. Add a subscription from the console or the portal API:

Each event type belongs to a scope family that governs how you may subscribe and how Krallo authorizes delivery:

Subscribing to a guild event you don't administer returns 403 not_guild_admin. The current catalog is AI-focused — see the event catalog for the live list and each event's data shape.

The event envelope

Every delivery body is a stable JSON envelope. The event-specific payload lives under data:

{
  "id": "01JBK9T4M2X7Q0R8V6N3D5Z1AB",
  "type": "imagine.completed",
  "api_version": "2026-07-12",
  "created_at": 1720000000,
  "scope": "user",
  "resource_id": "6f3a2c1e-9b0d-4e21-8a77-1c2d3e4f5a6b",
  "data": {
    "...": "event-specific fields"
  }
}

Request headers

Every POST Krallo makes to your endpoint carries this fixed set of headers:

Verify the signature

The signature scheme is Stripe-style HMAC-SHA256. The signed message is the exact timestamp and raw body, joined by a dot: t + "." + rawBody. Recompute the HMAC with your endpoint secret over the raw request bytes (before any JSON parsing), compare in constant time, and reject a stale t to defeat replays.

const crypto = require("crypto");

// secret = the whsec_... value shown once at endpoint creation
function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map(p => p.trim().split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ""));
}

See Signature verification for the full walkthrough, the replay window, and examples in more languages.

Responding to deliveries

To acknowledge a delivery, return any 2xx status. Krallo treats a delivery as failed when your endpoint:

• returns a non-2xx status (including any 3xx redirect — redirects are not followed);
• does not respond within the 10-second delivery timeout; or
• is unreachable (connection refused, TLS failure, DNS failure).

Krallo reads up to 64 KB of your response and stores a ~1 KB snippet for debugging in the delivery attempt log. Return quickly and do heavy work asynchronously — acknowledge first, process after.

Retries and dead-letter

A failed delivery is retried with exponential backoff. Delays grow from roughly 10 seconds and double on each attempt (10s, 20s, 40s, …) up to a ceiling of a few minutes; the schedule is stored in the database, so retries survive restarts. A delivery is attempted up to 12 times.

After the final attempt fails, the delivery is moved to the terminal dead state (dead-lettered) and its endpoint's consecutive-failure counter increments. A successful delivery resets that counter. If an endpoint accumulates 20 consecutive failed deliveries, it is automatically disabled and stops receiving fan-out until you re-enable it.

Idempotency and ordering

Because delivery is at-least-once, design your handler to be idempotent. Persist the X-Krallo-Event-Id (equal to the envelope id) and ignore an event id you have already processed. A single logical change is delivered under one stable event id no matter how many times it is retried.

Deliveries to a single endpoint are processed serially, but retries and backoff mean events can still arrive out of order. Do not rely on receipt order — use created_at and the resource's own state to order effects.

Replaying deliveries

Any delivery — dead-lettered or already delivered — can be re-driven through the same pipeline.

From the console: open the delivery in the Deliveries log and select Replay.

From the bearer API (requires the webhooks:write scope):

curl -X POST https://exe.krallo.com/api/v1/webhooks/deliveries/01JBK.../replay \
  -H "Authorization: Bearer krallo_live_..."

Replay returns 202 Accepted and resets the delivery to pending; the sweeper re-sends it on its next tick. Replay is scoped to your own apps — another developer's delivery id returns 404 not_found. A delivery that is currently in flight (sending) cannot be replayed and returns 409 delivery_in_flight; wait for it to settle, then retry.

To list and inspect deliveries, see the Webhook deliveries API reference.

Endpoint statuses

Limits

Next steps

• Signature verification — verify X-Krallo-Signature and reject replays.
• Event catalog — the subscribable event types and their data payloads.
• Webhook deliveries API — list, inspect and replay deliveries over the bearer API.
• Errors — status codes and error slugs used across the platform.