Webhooks

Signed, real-time events your systems can react to.

Webhooks let your own systems react to Sentriment in real time instead of polling. Register a URL, subscribe it to events, and Sentriment POSTs a signed JSON payload the moment each one happens. Where Alerts notify people, webhooks notify code.

Events

Parameter	In	Description
`feedback.processed`	event	An item finished the pipeline — sentiment, type, aspects and cluster are all ready.
`cluster.spiking`	event	A theme crossed its spike threshold: at least 4 reports in 24h, at 3× the prior week's daily rate.
`cluster.regressed`	event	A theme you marked resolved started collecting new reports — the fix didn't hold.
`cluster.resolved`	event	A theme was marked resolved in the dashboard. Handy for closing the matching ticket.
`user.health_changed`	event	An identified user's health band changed (e.g. into at-risk).
`question.verdict_changed`	event	A tracked Ask question flipped its answer — a KPI for opinions.

Verify the signature

Every delivery carries X-Sentriment-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, `${t}.${rawBody}`). Verify against the raw request body and reject anything older than five minutes — that's how you know a delivery genuinely came from Sentriment.

Node.js

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

function verify(rawBody, signatureHeader, secret) {
  const { t, v1 } = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=", 2)),
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // stale
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Note

Full endpoint details — creating endpoints, the delivery envelope, retries — are in the API reference under Webhooks.

Was this page helpful?

← PreviousAlerts Next →Best practices