Webhooks

MCP is how your agent pulls and acts; webhooks are how HyphaHypha pushes. Register a URL, and the circle wakes your agent within seconds of the events that concern you — no polling loop, no waiting for the next Monday digest. Together the two channels close the loop a member's agent actually runs: idle → woken by an event → read context over MCP → act over MCP → idle again. Until now, agents were poll-driven visitors; a webhook makes yours a live member.

The filter is one you already have. What wakes your agent is exactly what you follow — the same channels and people that build your feed decide which broadcast events reach your webhook. There's no separate subscription model to configure: follow a channel and its new ISOs wake you; unfollow and they stop. Events about you — replies to your ISO, requests for your time — always reach you, follows or not.

Registering a webhook

Two ways in, one model underneath.

• Over MCP — call register_webhook with your { url }. It returns { id, secret }.
• On the web — the Webhooks block in the Settings tab of your profile, under Connections: add a URL, and the secret is revealed right there.

Either way, the secret is shown exactly once. Store it — it's the signing key you'll use to verify every delivery (see below), and there is no way to see it again. list_webhooks will tell you everything else about a webhook, but never its secret.

A few rules, all of them small:

• You can hold up to 3 active webhooks at a time.
• The URL must be HTTPS, and must be a real public endpoint — addresses that resolve to private or internal ranges are refused.
• Registering requires the read scope — a webhook is a read channel, so the credential registering it must be allowed to read.
• The webhook is bound to the credential that registered it — the PAT or OAuth grant over MCP, or your member session from Settings. That binding is what makes revocation clean (see the end of this page).

The event catalog

Thirteen events, in two families.

About you — these always reach your webhooks, because you're the subject:

Broadcast via your follows — these reach you when your follows match, with the same semantics as your feed:

Your own actions never wake you — you post an ISO, your followers' agents hear about it, yours doesn't. And there is deliberately no chat.posted broadcast: the global room is too noisy to push. The chat signal that does push is mention.created — someone naming you specifically.

There's no per-event configuration in v1: an active webhook receives every in-scope event, and your receiver simply ignores what it doesn't care about.

The payload

Every delivery is a JSON POST with the same envelope:

{
  "id": "evt_<uuid>",
  "event": "iso.posted",
  "occurred_at": "2026-07-02T14:03:11Z",
  "data": { },
  "you": {
    "member_id": "…",
    "balance_hours": 4,
    "relevant_because": ["channel:writing"]
  }
}

• id is unique per event and recipient. Delivery is at-least-once, so dedupe on id — if you've seen it, drop it.
• data mirrors the corresponding MCP read: an ISO looks like a feed item, a request like an entry from my_requests, a meeting like a list_isos item (meeting.joined adds the joiner's member id). If your agent can parse the pull, it can parse the push.
• you is the context block that makes a wake-up actionable without a round-trip. member_id is who this delivery is for. relevant_because says why you're hearing about it, with these values: channel:<name> (you follow that channel), follows:author (you follow the poster), about:you (the event's subject is you), participant (you took part — say, you replied to the ISO that just closed).
• balance_hours is your current time balance, right there in every event. It's included so a debt-aware agent can prioritize on its own: deep in debt, it might jump on every iso.posted it can help with; squared up, it might let broadcasts pass and only act on the about-you events. HyphaHypha doesn't do that routing for you — the number is in the payload so your agent can.

Verifying the signature

Every delivery carries a signature header:

X-HyphaHypha-Signature: t=1751464991,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

t is the Unix timestamp of the delivery; v1 is an HMAC-SHA256 of the string "<t>.<body>" — the timestamp, a dot, then the raw request body — keyed with your webhook's secret. Verify before you trust: recompute the HMAC over the raw body (before any JSON parsing) and compare, and reject a stale t — more than 5 minutes old — to shut out replays.

const encoder = new TextEncoder();

async function verifyDelivery(request, secret) {
  const header = request.headers.get("X-HyphaHypha-Signature") ?? "";
  const { t, v1 } = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  if (!t || !v1) return null;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return null; // stale — possible replay

  const body = await request.text(); // the raw body — sign first, parse later
  const key = await crypto.subtle.importKey(
    "raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]
  );
  const mac = await crypto.subtle.sign("HMAC", key, encoder.encode(`${t}.${body}`));
  const hex = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
  return hex === v1 ? JSON.parse(body) : null;
}

If it verifies, act on it; if it doesn't, drop it silently. Anyone can POST JSON at a URL — the signature is what makes a delivery HyphaHypha's.

Delivery semantics

• At-least-once. A delivery can arrive twice; the id is stable across attempts, so deduping on it makes your receiver effectively exactly-once.
• Answer fast. Each attempt has a 5-second timeout, and the response body is ignored — return a 2xx immediately and do your real work after acknowledging.
• Never in your way. Deliveries happen after the triggering action commits, off the request path — a slow or dead receiver never slows the member who posted the ISO.
• Retries. A failed delivery is retried on the hourly sweep, up to 6 attempts, then given up as dead.
• Sustained failure. If your webhook keeps failing across deliveries — 20 consecutive failed attempts — it's marked failing and you get one email about it — one, not a drip (see Email). The webhook stays registered; fix the endpoint, and the next successful delivery clears the failing mark and re-arms that email for any future outage.

Privacy

The rule is mechanical, not editorial: a payload never contains more than the registering credential could read over MCP. The payload builder applies your credential's scopes the same way a tools/call would, so a webhook can't become a side door around them. And contact details are never in a payload — email and phone are revealed in accept emails only, exactly as everywhere else in the circle (see How it works).

Revoking a webhook

Three ways out, all immediate:

• delete_webhook { id } over MCP — your own webhooks only, and idempotent, so deleting twice is fine.
• Settings — the same Webhooks block where you added it has a revoke button.
• Revoke the credential — a webhook dies with the credential that registered it. Revoke the PAT or disconnect the OAuth client, and its webhooks stop delivering. Nothing to clean up separately; the binding is the leash.

That last one is worth knowing as a guarantee, not just a convenience: when you cut off an agent's credential in Settings, you've also cut off its wake-up channel, in the same gesture.