Webhooks

​

The delivery contract

• At-least-once. The same event can be delivered more than once — deduplicate on the event id.
• Unordered. A retried earlier event can arrive after a later one — order by the event’s date, never by arrival time.
• Signed. Always verify the signature before trusting a payload.

​

Setting up a webhook

• Entities — the entity or entities (your organization’s operating units in Fortary) whose events the webhook receives.
• Event types — an explicit list of the event kinds to deliver. There are no wildcards; new kinds are opt-in.
• Vault filter (optional) — restrict vault-scoped events to specific vaults.
• Notification email — where Fortary sends operational notices, for example an automatic disable.

​

Authorization

​

Operations

​

Your first handler

import { createServer } from "node:http";
import { verifyWebhookSignature } from "./verify-webhook-signature.js"; // from Verifying signatures

const secret = process.env.FORTARY_WEBHOOK_SECRET ?? ""; // whsec_…

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks).toString("utf8");
    const signature = req.headers["x-fortary-signature"];

    if (typeof signature !== "string" || !verifyWebhookSignature({ secret, signature, rawBody })) {
      res.writeHead(400).end();
      return;
    }

    res.writeHead(200).end(); // acknowledge before doing real work

    const event = JSON.parse(rawBody);
    // hand `event` to your queue / worker here — deduplicate on event.id
  });
}).listen(8080);

​

Guides

• Event types — every event kind, the envelope, and payload examples
• Verifying signatures — the signature scheme with working code
• Delivery & retries — the retry schedule, automatic disabling, and redelivery