Signed webhooks

Create workspace-wide or project-scoped endpoints from Dashboard → Developer or with create_webhook. URLs must use HTTPS and resolve to public addresses; credentials, fragments, nonstandard ports, private IP ranges, localhost, and redirects are rejected.

{
  "id": "evt_...",
  "type": "mention.created",
  "apiVersion": "2026-08-24",
  "createdAt": "2026-08-24T09:30:00.000Z",
  "projectId": "...",
  "data": { "mention": { /* source-compliant fields */ } }
}

The event id is stable across retries and can be used for receiver-side deduplication.

Read the raw request body before JSON parsing. Join webhook-id, webhook-timestamp, and the raw body with period separators, compute HMAC-SHA256 with the endpoint secret, Base64-encode it, and compare it in constant time with the v1 value in webhook-signature.

import crypto from "node:crypto";

const signed = [
  request.headers.get("webhook-id"),
  request.headers.get("webhook-timestamp"),
  rawBody,
].join(".");

const expected = crypto
  .createHmac("sha256", process.env.STALKR_WEBHOOK_SECRET)
  .update(signed)
  .digest("base64");

const provided = request.headers
  .get("webhook-signature")
  ?.replace(/^v1,/, "");

const valid = provided && crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(provided)
);

A success is any HTTP 2xx response. Failed deliveries retry up to eight times with increasing delays from one minute to 48 hours. Requests time out after ten seconds, never follow redirects, and retain only a bounded response preview. Twenty consecutive failures automatically disable an endpoint.

Events and delivery history are retained for 30 days. You can inspect attempts, queue a test, replay a retained delivery, rotate the secret, or re-enable a healthy endpoint.