Webhooks

A webhook endpoint is an https address of yours that Noru calls when something happens in your organization: a risk is created, a policy is approved, a supplier reports a breach. Each call is a POST with a JSON body describing one event, called a signal, and a signature you check with the endpoint's secret. Deliveries follow the open Standard Webhooks specification, so any Standard Webhooks library can verify them.

This page is the technical contract. For the settings screens, see Webhook settings.

How delivery worksCopy Anchor Link

The requestCopy Anchor Link

Every attempt carries these headers:

Payload formatCopy Anchor Link

The body is one signal:

{
  "id": "NORU-SIG-1042",
  "type": "risk.updated",
  "time": "2026-03-10T12:00:00.000Z",
  "organizationId": "org_2abc123def456",
  "subject": { "type": "risk", "id": "NORU-RISK-12" },
  "data": {
    "record": {
      "id": "NORU-RISK-12",
      "title": "Phishing leads to account takeover",
      "status": "mitigating",
      "riskLevel": "high",
      "ownerId": "user_2abc",
      "dueDate": "2026-06-30T00:00:00.000Z"
    },
    "changes": {
      "status": { "from": "assessing", "to": "mitigating" }
    }
  }
}

For the record signals (*.created, *.updated, *.deleted), data.record is the record as it is after the change (or just before it was deleted), and *.updated adds data.changes: one entry per field that changed, with from and to. Other signals carry their own fields. The API reference lists the exact schema and an example for every type under Webhooks, and the OpenAPI document carries them in its webhooks section if you want to generate types.

Verify the signatureCopy Anchor Link

Verify every delivery before you trust its body. Check three things:

1. The signature. Compute HMAC-SHA256 over the exact string <webhook-id>.<webhook-timestamp>.<raw body>, keyed with the endpoint's secret, and compare it with each v1, entry in webhook-signature.
2. The key. The secret looks like whsec_<base64>. The key is the part after whsec_, base64-decoded to 32 bytes. Using the text of the secret as the key is the most common mistake.
3. The timestamp. Refuse a webhook-timestamp more than five minutes from your clock, so a captured request cannot be replayed later.

With a Standard Webhooks libraryCopy Anchor Link

The quickest correct option. Libraries exist for most languages; they accept the whsec_ secret as Noru shows it, check the timestamp, and compare in constant time.

npm install standardwebhooks express

import express from "express"
import { Webhook } from "standardwebhooks"

const webhook = new Webhook(process.env.NORU_WEBHOOK_SECRET) // "whsec_..."
const app = express()

app.post(
  "/noru/webhooks",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    let event
    try {
      event = webhook.verify(req.body.toString("utf8"), req.headers)
    } catch {
      return res.status(401).send("invalid signature")
    }
    if (await alreadyProcessed(req.headers["webhook-id"])) {
      return res.sendStatus(200) // a retry of something you already handled
    }
    await enqueue(event) // do the work after answering
    res.sendStatus(204)
  }
)

app.listen(3000)

Without a libraryCopy Anchor Link

The same check in a few lines, if you would rather not add a dependency.

import crypto from "node:crypto"

const TOLERANCE_SECONDS = 5 * 60

/** Returns the parsed event, or throws when the delivery is not from Noru. */
export function verifyNoruWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"]
  const timestamp = headers["webhook-timestamp"]
  const signatures = headers["webhook-signature"]
  if (!id || !timestamp || !signatures) {
    throw new Error("Missing webhook headers")
  }

  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
    throw new Error("Timestamp too old or too new")
  }

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64")
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest("base64")

  const matches = signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",")
    return (
      version === "v1" &&
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    )
  })
  if (!matches) {
    throw new Error("Invalid signature")
  }
  return JSON.parse(rawBody)
}

Check one delivery by handCopy Anchor Link

To see whether your secret is right, recompute the signature of a delivery you received (or one from the delivery log, see Debug a failing endpoint) in a shell. Save the raw body to body.json exactly as received, then:

SECRET='whsec_...'          # the endpoint's secret
ID='msg_...'                # the webhook-id header
TS='1773144000'             # the webhook-timestamp header
KEY_HEX=$(printf '%s' "${SECRET#whsec_}" | base64 -d | od -An -v -tx1 | tr -d ' \n')
printf '%s.%s.' "$ID" "$TS" | cat - body.json \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$KEY_HEX" -binary | base64

The output must equal the part after v1, in the webhook-signature header.

Respond quickly and handle retriesCopy Anchor Link

• Answer within 10 seconds with any 2xx. Put slow work on a queue and answer first; a timeout counts as a failure even if your work later succeeds.
• Any other answer fails the attempt: a 4xx or 5xx, a redirect, a timeout, a refused connection or a TLS error. Noru tries again after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours: seven attempts over about a day and a half. Then the delivery is marked Failed, and you can still send it again by hand.
• Ten failed attempts in a row turn the endpoint off, whichever deliveries they belong to. Pending retries for it are not sent. Fix the receiver, then turn the endpoint back on in settings; that clears the count. Signals that happen while an endpoint is off are not delivered to it later. Deliveries that were waiting for a retry show as Not sent, and you can redeliver them one by one.
• Answer 2xx to signal types you do not handle. Ignoring is a success; failing would only cause retries and could turn the endpoint off.

Drop duplicatesCopy Anchor Link

A delivery can arrive more than once: when your 2xx was lost on the way back, when Noru retries after a timeout, or when someone redelivers it. webhook-id is the same each time, so record it (for a day or two is enough) and skip a delivery whose id you have already processed. The body's id is the signal id: two endpoints receiving the same signal see the same id but different webhook-ids.

Test your receiverCopy Anchor Link

Use Send test delivery in the endpoint's menu under Settings›Webhooks, or POST /v1/webhook-endpoints/{id}/test. Noru sends a signed delivery of type webhook.test right away, whatever signal types the endpoint subscribes to, and shows what your endpoint answered:

{
  "id": "test_x8Kq2mV0uZsd1Yh3",
  "type": "webhook.test",
  "time": "2026-10-18T09:30:00.000Z",
  "organizationId": "org_2abc123def456",
  "subject": { "type": "webhook_endpoint", "id": "NORU-WHK-3" },
  "data": {
    "message": "A test delivery from Noru. If your receiver verified its signature, it is ready."
  }
}

A test delivery is signed, logged and retried exactly like a real one, and a failed one counts towards turning the endpoint off. Answer 2xx to webhook.test once your signature check passes.

Debug a failing endpointCopy Anchor Link

Every delivery and every attempt is kept in the delivery log under Settings›Webhooks›Deliveries. Click a row to open it. For a delivery you see:

• The request: the endpoint address, the headers (webhook-id, webhook-timestamp per attempt, Content-Type, User-Agent) and the exact JSON body that was signed.
• Every attempt, newest first: when it was sent, the HTTP status your endpoint answered, how long it took, and the first 4 KB of its response body. Return a short error message in your response body and you will see it here.

The same data is available from GET /v1/webhook-deliveries/{id} and the getWebhookDelivery MCP tool. When an attempt failed, the log names why:

Fix the cause, then click Redeliver on the delivery. It is sent again now, with the same webhook-id.

Rotate the secretCopy Anchor Link

Rotate secret in the endpoint's menu creates a new secret and shows it once. The old secret stops working at once, so deploy the new one to your receiver straight away; deliveries in between fail the signature check and are retried. During a planned switch you can have the receiver accept either secret for a few minutes.

If a secret leaks, rotate it. Nothing else is needed: the endpoint address is not a secret.

Messages from workflowsCopy Anchor Link

A workflow's Send a webhook step posts to one of these endpoints, signed with its secret, with the same headers. Its body is the step's message rather than a signal:

{
  "id": "NORU-RUN-88:notify_siem",
  "type": "workflow.webhook",
  "time": "2026-10-18T09:30:00.000Z",
  "organizationId": "org_2abc123def456",
  "workflow": { "id": "NORU-WF-4", "name": "Escalate critical risks" },
  "run": { "id": "NORU-RUN-88" },
  "data": { "riskId": "NORU-RISK-12", "title": "Phishing leads to account takeover" }
}

• type is the step's Event name (workflow.webhook unless you change it).
• data is the step's Data, with its {{ }} values filled in from the run.
• webhook-id and id are both <run id>:<step id>, the same on each attempt.
• The workflow retries the step itself, a few times within minutes, and then the run fails. These messages appear in the delivery log with a link to the run.

See Build a workflow.

Signal typesCopy Anchor Link

An endpoint receives only the types it subscribes to. Types marked Supplier risk exist only in organizations with supplier risk management.

GET /v1/webhook-endpoints also returns the list of types your organization can subscribe to, with a label and description for each.

Manage endpoints with the APICopy Anchor Link

Everything in the settings tab is also available over the REST API with an API key holding read:webhooks or write:webhooks, and as MCP tools with the same names:

What Noru does not doCopy Anchor Link

• It does not send to http addresses, private networks, or addresses that redirect.
• It does not sign with anything but the endpoint's secret. There are no fixed source IP addresses to allow-list; verify the signature instead.
• It does not batch: one delivery is one signal.
• It does not guarantee order, and it does not keep sending to an endpoint it turned off.
• It does not store your full response: only its status and its first 4 KB.

RelatedCopy Anchor Link

• Webhook settings: add endpoints and read the delivery log in the app
• Inbound hooks: the other direction, other systems calling Noru
• Workflows
• API keys and REST API