Tunnel webhook events

​

Event types emitted by tunnel

const catalog = await trpc.webhooks.catalog.query({ orgId });
const tunnelTypes = catalog.tunnel.groups.flatMap((g) => g.types);

• test.ping — what the Test button sends via webhooks.sendTest. It is a fully signed delivery that appears in the delivery log like any other, so it is the right way to prove signature verification and network reachability before you wait for real sessions.
• * — not an event, a wildcard subscription. See below.

​

How event type matching works

• the pattern equals the event type, or
• the pattern is *, or
• the pattern ends in .* and the event type starts with the prefix before the *.

• Selecting every group collapses to ['*']. An endpoint stored as * is subscribed to everything in the tunnel registry including event types added to the registry later. If you want a frozen subscription set, deselect at least one group so the endpoint stores explicit tokens.
• The “Event groups” column is derived, not stored. The row shows a group’s label when the endpoint’s stored patterns cover any of that group’s types. An endpoint stored as * renders as every group label. Patterns that match no group at all are shown verbatim as raw tokens.

​

Session lifecycle: when each event fires

• Open fires when a session is admitted. It is the first event for a session id and marks the start of the session’s lifetime.
• Close fires when that session tears down. Paired with the open event for the same session, it bounds the session’s duration.
• Reject fires when an attempt is refused. A rejected attempt never became a session, so it is reported by the reject event alone — there is no open or close event to pair with it.

​

Subscribing an endpoint to session events

• URL scheme. https:// by default. An http:// URL is rejected with BAD_REQUEST unless the endpoint is created with allowPrivateEgress: true — the On-prem / private-network endpoint checkbox. That flag is also what permits RFC1918 targets.
• Reachability. Both create and update call assertDeliverableOrBadRequest(url, allowPrivateEgress), so an undeliverable target fails at configuration time rather than becoming a dead endpoint.
• Lengths. URL up to 2048 characters; description up to 300.
• Scheme changes on update. webhooks.update validates a new URL against the stored allow_private_egress flag of that row, not against anything in the request. Moving an existing endpoint to http:// therefore fails unless the row was created as on-prem.

​

Verifying a delivery

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

function verify(headerValue: string, rawBody: string, secret: string) {
  const parts = new Map(
    headerValue.split(",").map((kv) => kv.split("=") as [string, string]),
  );
  const t = parts.get("t");
  const v1 = parts.get("v1");
  if (!t || !v1) return false;

  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(v1, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

​

What the delivery log records

​

Worked example: session audit trail into a SIEM

const { id, secret } = await trpc.webhooks.create.mutate({
  orgId,
  vertical: "tunnel",
  url: "https://siem-shim.internal.example/hooks/tunnel",
  description: "SIEM shim — session audit trail",
  eventTypes: ["*"],
  allowPrivateEgress: false,
});
// `secret` is returned once. Put it in your secret manager now.

app.post("/hooks/tunnel", async (req, res) => {
  const sig = req.header("x-clutchcall-signature") ?? "";   // see note above
  const raw = req.rawBody.toString("utf8");

  if (!verify(sig, raw, process.env.TUNNEL_WEBHOOK_SECRET!)) {
    return res.status(401).end();
  }

  const event = JSON.parse(raw);
  await siem.ingest({ source: "tunnel", eventType: event.type, raw: event });
  res.status(204).end();
});

​

Related

• Authentication — API keys for the control plane
• Telemetry — metrics and traces alongside webhook events