Webhooks

Get an HTTP call the moment something happens in your pipeline: a candidate applies, moves stage, is hired, or finishes and is scored on their Stori interview. How to add an endpoint, what Stori sends, and how to verify every request.

Overview

A webhook is a URL you own that Stori calls with a JSON body whenever a chosen event happens in your workspace. Use it to keep another system in step with Stori without polling: update a spreadsheet when a candidate moves stage, post to a channel when an interview is scored, or start your own onboarding when someone is hired.

  • Endpoints live under Settings > Integrations > Webhooks. Admins add, edit and delete them; everyone can see them and the delivery log.
  • Each endpoint has its own signing secret, shown once when you create it. Store it where your server can read it.
  • You choose which events an endpoint receives. Nothing is sent for events you have not subscribed to.

If all you want is updates in a Slack channel, you do not need a webhook. Run /stori watch <job title> in the channel instead. See Stori in Slack.

Add an Endpoint

1.

Open Webhooks

Go to Settings > Integrations and choose Webhooks, then click Add endpoint.

2.

Fill in the endpoint

Enter the Endpoint URL, which must be HTTPS, and an optional Description so your team knows what it feeds.

3.

Pick the events

Under Subscribe to events, tick the events you want, or Select all.

4.

Save and copy the secret

Click Create endpoint. The signing secret appears once; copy it now, because it will not be shown again.

Each endpoint card shows whether it is Active, the start of its secret, and how many deliveries have failed in a row. Edit changes the URL, the events, or switches it off with Endpoint enabled (a disabled endpoint keeps its settings but receives nothing).

Events

Every delivery carries the event name in the X-Stori-Event header and in the body. These are the events Stori sends:

Candidates

  • candidate.applied: someone applied to one of your jobs, from any source.
  • candidate.stage_changed: a candidate moved between pipeline stages.
  • candidate.hired, candidate.rejected: a candidate was marked hired or rejected. A rejection includes the reason.
  • candidate.unrejected: a rejection was reversed.
  • application.updated: an application's outcome changed, such as hired or rejected. It is sent alongside the candidate event, with the same action id.

Interviews

  • interview.completed: a candidate finished their Stori interview.
  • interview.scored: the interview has been analysed against the job; the analysis is in the payload.
  • interview.red_flags_detected: the analysis flagged something the team should look at, listed in the payload.
  • interview.no_show: a candidate did not turn up to an interview your team scheduled.

The event picker lists Stori's full catalogue, including job, offer and scheduling events that are not sent yet. You can subscribe to them now; they will arrive once Stori starts sending them.

What a Delivery Looks Like

Stori sends an HTTP POST with a JSON body:

{
  "id": "...",
  "action_id": null,
  "type": "candidate.stage_changed",
  "created_at": "2026-11-04T09:30:00.000Z",
  "api_version": "2026-05-01",
  "data": { ... }
}

data holds the records the event is about, such as the candidate and the application. The headers:

Header Meaning
X-Stori-Event The event name, for example candidate.stage_changed
X-Stori-Delivery-Id Unique per delivery. The same id is reused on every retry of that delivery, so you can ignore duplicates
X-Stori-Timestamp Unix seconds when the request was signed
X-Stori-Signature t=<unix-seconds>,v1=<hex>, see below
X-Stori-Action-Id Present when one action caused several events, so you can group them
User-Agent Stori-Webhooks/1.0

Respond with any 2xx status within ten seconds. Do your real work after replying, not before.

Retries

A delivery that does not get a 2xx is retried, up to eight attempts over about three and a half days, with the wait growing between attempts: one minute, then five, thirty, two hours, six, twelve, and a day. After the last attempt the delivery is marked Exhausted in the delivery log, where you can Replay it by hand. After 50 failures in a row an endpoint is switched off and marked Auto-disabled, so a dead URL does not keep a queue growing; fix the URL and switch it back on with Edit.

Verifying the signature

Verify every request before trusting it. The signature is an HMAC-SHA256 over the timestamp and the exact raw body, joined by a full stop, using your endpoint's secret:

v1 = HMAC-SHA256( secret, "<X-Stori-Timestamp>.<raw request body>" )

Compare it to the v1 value in X-Stori-Signature using a constant-time comparison, and reject requests whose timestamp is more than five minutes old so a captured request cannot be replayed. Always sign the raw bytes you received, not a re-serialised copy: any change in whitespace or key order produces a different hash.

Read the raw body before your framework parses it as JSON. Express, Next.js and Flask all parse by default, and a parsed-then-stringified body will not match.

Node

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

export function verifyStoriWebhook(rawBody, headers, secret, toleranceSeconds = 300) {
  const [tPart, v1Part] = (headers["x-stori-signature"] || "").split(",");
  const timestamp = tPart?.slice(2);
  const received = v1Part?.slice(3);
  if (!timestamp || !received) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Python

import hmac, hashlib, time

def verify_stori_webhook(raw_body: bytes, headers: dict, secret: str, tolerance: int = 300) -> bool:
    header = headers.get("X-Stori-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    timestamp, received = parts.get("t"), parts.get("v1")
    if not timestamp or not received:
        return False
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    message = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

Go

func verifyStoriWebhook(rawBody []byte, signatureHeader, secret string, tolerance time.Duration) bool {
	var ts, received string
	for _, part := range strings.Split(signatureHeader, ",") {
		if strings.HasPrefix(part, "t=") {
			ts = part[2:]
		} else if strings.HasPrefix(part, "v1=") {
			received = part[3:]
		}
	}
	if ts == "" || received == "" {
		return false
	}
	unix, err := strconv.ParseInt(ts, 10, 64)
	if err != nil || time.Since(time.Unix(unix, 0)).Abs() > tolerance {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(ts + "."))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(received))
}

If the secret is ever exposed, open the endpoint with Edit and click Rotate beside Signing secret. New deliveries are signed with the new secret at once, so update your server straight away. Deliveries already queued keep the secret they were signed with, so retries in flight still verify against the old one.

Testing an Endpoint

Click Test on the endpoint's card to send a sample event with a real signature. Then click Log, or Delivery log at the top of the tab, to see every delivery: when it was sent, the event, the endpoint, its status with the HTTP code your server returned, and how many attempts it took. Filter the log by status (Delivered, Pending / retrying, Failed, Exhausted), and Replay any delivery to send it again.