Webhooks

Call events sent to your systems: call.answered, call.completed (with the result and transcript), call.failed and call.data. Failed deliveries are retried for about a day.

Signing secret

Every webhook carries an X-SingleStaff-Signature header: t=<time>,v1=<signature>, an HMAC-SHA256 of <t>.<raw body> made with this secret. Check it on your server to know the request came from us and wasn't changed.

How to verify (Node.js)
import crypto from "node:crypto";

// Use the raw request body (before JSON parsing).
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // too old: replay
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

// verify(rawBody, req.headers["x-singlestaff-signature"], process.env.SINGLESTAFF_WEBHOOK_SECRET)

Send a test event

Deliveries

Show
WhenEventCallStatusAttemptsLast response