Interlinked docs: the CLI, MCP, webhooks and the REST API

Every query kind, measured: medians, not cherry-picks.

Real end-to-end latency with full ranking on a live, freshly cold-built index: the honest distribution, worst cases and all. Beside each, what the same job costs the scanner your AI uses today.

Real searches on one real PC, a Ryzen 9 on Windows 11, same machine and same queries for both. And ripgrep isn’t a strawman: it’s the search engine inside VS Code and the one AI agents like Claude Code run. Full methodology in the ripgrep comparison.

One URL, the events you want, and a signing secret you see exactly once. Needs someone who manages the project, or a key at write with the webhook scopes, because forwarding a project's activity to a URL is a disclosure decision and somebody who can push is not automatically somebody who decides where its history gets mirrored.

curl -X POST https://api.interlinkedfiles.com/v1/projects/$PROJECT/webhooks \
  -H "authorization: Bearer $ILK_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "url": "https://acme.example/hooks/interlinked",
    "events": "version.pushed",
    "format": "interlinked"
  }'

# { "ok": true,
#   "endpoint": { "id": "b1f0...", "events": "version.pushed" },
#   "secret": "whsec_kR8vN2pQ7xY4mL1cJ9bF6tW3sH5dZ0aG8eU2iO4yV6k=" }

The signing secret comes back exactly once, like the key. `events` takes `*` or a space-separated subset of the three. Creating an endpoint needs `webhook:write` on a key at write on the project (a person needs to manage the project): forwarding a project's activity to a URL is a disclosure decision, and somebody who can push is not automatically somebody who decides where its history gets mirrored. https only, and a URL naming a private or loopback address is refused, because otherwise anyone who can create an endpoint can make our Worker probe an internal service and read the result out of the delivery log.

Standard Webhooks, so an off-the-shelf library you may already have for another provider verifies us with no code at all. Both of these are cross-checked against node's own createHmac by scripts/integrations.test.mjs.

import { createHmac, timingSafeEqual } from "node:crypto"

// The RAW body. Not a parsed-and-restringified one: JSON.stringify is not
// canonical, so re-serializing is a signature that fails on somebody else's
// JSON library. Read the bytes before your framework parses them.
export function verify(headers, rawBody, secret) {
  const id = headers["webhook-id"]
  const ts = Number(headers["webhook-timestamp"])
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false

  const key = Buffer.from(secret.slice("whsec_".length), "base64")
  const want = "v1," + createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64")

  // ANY of the space-delimited signatures matching is a pass. That is what
  // makes a secret rollover invisible to you: for 24 hours we send two.
  return String(headers["webhook-signature"]).split(" ").some((got) => {
    const a = Buffer.from(got), b = Buffer.from(want)
    return a.length === b.length && timingSafeEqual(a, b)
  })
}

This is the Standard Webhooks scheme, so an off-the-shelf library you may already have for other providers verifies us with no code at all. Two things that bite: the key material is the base64 AFTER the `whsec_` prefix, decoded, and the signed string is `id.timestamp.body` rather than the body alone.

import base64, hashlib, hmac, time

def verify(headers, raw_body: bytes, secret: str) -> bool:
    msg_id = headers["webhook-id"]
    ts = int(headers["webhook-timestamp"])
    if abs(time.time() - ts) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + raw_body
    want = "v1," + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    got = headers["webhook-signature"].split(" ")
    return any(hmac.compare_digest(g, want) for g in got)

Identifiers and counts, never content. A leaked endpoint URL then leaks nothing, the content comes from the read API with your own key so the egress meters against the right account, and at the moment a version lands we genuinely do not hold the file list to send you. This is a real delivery, captured from production.

webhook-id:         41e89e83-c577-47c2-b49e-8f73e322e2c4
webhook-timestamp:  1789617718
webhook-signature:  v1,K7mXq2pR8vN4yL1cJ9bF6tW3sH5dZ0aG8eU2iO4yV6k=
x-interlinked-event: version.pushed

{
  "id": "41e89e83-c577-47c2-b49e-8f73e322e2c4",
  "type": "version.pushed",
  "created": 1789617718,
  "object": {
    "type": "version",
    "id": "22b7a5169813690551e0a9e4a8a50429f1e43e8969770be8d2b4a86489a9e4bc",
    "url": "/p/orbital-freight?w=version&rev=12"
  },
  "data": {
    "repository": "01a0a861f4e977e3a363258c20d2c023",
    "project": "orbital-freight",
    "number": 12,
    "message": "ENG-123 dock doors open inward",
    "by": "person",
    "ref": { "keyType": null, "key": "main" },
    "branch": "main",
    "before": "9c1f04d2a7e35b8860f1d3c2e4a5b6978d0e1f2a3b4c5d6e7f8091a2b3c4d5e6",
    "after": "22b7a5169813690551e0a9e4a8a50429f1e43e8969770be8d2b4a86489a9e4bc",
    "actor": { "userId": "DL8UDi...", "email": "[email protected]", "name": "Someone" },
    "actorConfidence": "token",
    "at": 1789617718
  }
}

A few fields deserve a word. `number` is the save's number on its branch and `message` is what the person wrote on it, up to 2,000 characters, so an issue id in a message is yours to find; `object.url` opens that exact version. `by` is `person`, `agent` or null: whether a person or an AI agent made the save, when the save says. `before` is empty rather than a zero hash on a first push, so you do not have to know what our zero hash looks like. `branch` is null whenever we cannot honestly name the ref: the store key is a hash, and printing a guessed branch name into your channel would be worse than printing none, so `ref.key` is the thing you can rely on. And `actorConfidence` is `token`, `hook` or `none`: `token` means the vault's own push moved the head and the pusher is the account whose token asked, `hook` means the vault named the pusher for this exact revision after the push landed, `none` means that did not arrive in time and the event went out on the pointer move alone. Exact or absent, never a guess. Do not authorize or bill off it.

Three event names, and the list ships short on purpose: every name is a permanent public commitment, so it grows on demand rather than being wrong in public.

// The container moved. One event, one field to switch on.
{ "type": "project.changed",
  "data": { "change": "visibility", "visibility": "public",
            "repository": "01a0a861...", "project": "orbital-freight" } }
// change: published | retracted | deleted | restored | visibility

// Access moved. The event nobody thinks of until an auditor asks.
{ "type": "member.changed",
  "data": { "change": "rung", "userId": "DL8UDi...", "permission": "admin",
            "previousPermission": "write", "actorUserId": "DL8UDi...",
            "repository": "01a0a861...", "project": "orbital-freight" } }
// change: granted | rung | revoked | owner
// permission is one of: read, write, admin, officer, owner

These two are written down with the change itself and sent as soon as it is saved, usually within seconds. If that send fails they go out within the next minute or two. They never wait on your endpoint to answer: a person clicking a button does not feel your latency.

Your endpoint will be down at some point. Here is exactly what we do about it, so you can decide how much you need to care.

Ten attempts over about seventy five hours, which survives a weekend. For comparison, GitHub gives you ten seconds and then does not retry at all.

• Answer with any 2xx within five seconds. Do the work after.
• Check the signature against the raw body with your secret.
• The same event can arrive twice. Ignore a webhook-id you have seen.
• A failed send is tried again: ten tries over about three days.
• After five days of failing the endpoint is switched off and you get a mail. Answer 410 to switch it off at once.
• Every attempt is recorded with the status code you answered, and any recorded event can be sent again: one at a time, or everything since a date. Send test posts one ping event and tells you at once what your service said. We do not promise ordering, and nobody sane does: retries reorder by construction. Treat each event as a notification and read current state from the API.
• Redelivery reuses the same webhook-id, so dedupe on that and a replay after your outage costs you nothing.
• Want work done when a save lands, with its result saved back? That is an action: two files in the project, run on your machine, your team's, or ours. Actions has every key, the price, two worked examples, and the same with a webhook and a key for anyone who would rather run their own pipe.

The roadmap

20 moments. What the three could cover, and what they cover today.

20 points, in the order they happen. 16 send a webhook; 4 are steps that need none. 4 of the 16 are live today. The rest are listed with their current state, so you can tell what you can build on now from what you would be waiting for.

Almost every line below is a kind of one of the three above rather than a name of its own. Nothing here is a fourth event waiting to be added.