Webhooks

A webhook endpoint is a URL Krrim delivers events to. Take events instead of polling and you stop spending rate-limit budget on questions whose answer is usually "nothing changed".

Create endpoints in Settings → Webhooks (organization owner or admin), or through /api/v1/webhooks/endpoints/ with the webhooks:write scope.

The envelope

Every delivery is a POST with the same top-level shape, whatever the event:

{
  "id": "evt_01J8Z9K3QW5N7T2R",
  "type": "task.status_changed",
  "api_version": "v1",
  "occurred_at": "2026-08-25T09:14:03.117000Z",
  "source": "web",
  "correlation_id": "cor_01J8Z9K3QW5N7T2S",
  "organization": { "id": 3, "slug": "acme", "name": "Acme" },
  "actor": { "id": 14, "email": "dana@acme.com", "name": "Dana Okafor" },
  "data": {
    "task": { "key": "krrim-0042", "title": "Investigate checkout timeout" },
    "from": "in_review",
    "to": "done"
  }
}

Event catalog

webhook.test is delivered but not subscribable: it goes to one endpoint because a human pressed the button on that endpoint, which is a stronger statement of intent than a checkbox.

The live catalog, including which events are subscribable, is at GET /api/v1/webhooks/catalog/.

Verifying a delivery

Every request carries a signature over the timestamp and the raw body:

X-Krrim-Signature: sha256=<hex>
X-Krrim-Timestamp: 1756113243

The signed string is {timestamp}.{raw_body}, HMAC-SHA256 with your endpoint's signing secret.

import hashlib, hmac, time

def verify(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Reject anything too old: the timestamp is inside the digest precisely so
    # a captured delivery cannot be replayed against you forever.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

There is also POST /api/v1/webhooks/verify/, which checks a signature for you while you are getting an integration working.

Retries

If your endpoint does not answer 2xx, Krrim retries on a fixed, published curve:

1 minute → 5 minutes → 30 minutes → 2 hours → 6 hours

Six attempts in total, then the delivery is abandoned. The curve is fixed rather than exponential-with-jitter because integrators size their outage tolerance against it, and a number you cannot predict is not one you can plan around.

• 5 second timeout per attempt.
• Redirects are never followed. A 3xx is a failure.
• Answer 2xx as soon as you have durably accepted the event; do the work afterwards. A slow handler burns the timeout and turns a successful delivery into a retry.

Auto-disable

An endpoint is disabled automatically after 20 consecutive abandoned deliveries — deliveries, not attempts. Counting attempts would let a half-hour outage on a busy workspace disable a perfectly healthy endpoint.

You are notified when it happens, and re-enabling is a click.

Replay

Delivery history is kept and browsable, and any delivery can be replayed:

POST /api/v1/webhooks/deliveries/{id}/replay/

A replay re-sends the original envelope and the original event id, not a fresh snapshot of the resource. That is what makes it useful for backfilling a consumer that was down: you get what you would have got at the time, not what the task looks like now. Your deduplication on id will see it as the same event.

URL requirements

Endpoint URLs must be HTTPS, and must not resolve to a loopback, private (RFC1918) or link-local address.