Docs · API · Webhooks

Webhooks.

Get pushed the moment a job finishes instead of polling for it. Deliveries follow the Standard Webhooks spec — the same signing scheme used by OpenAI, Anthropic, and Svix — so existing verifier libraries work unchanged.

Register an endpoint#

POST/v1/webhooks

Field	Type		Description
url	string (url)	required	Where events are POSTed. Must be https in production.
events	("job.succeeded" \| "job.failed")[]	default: both	Which events this endpoint receives.

Request

curl -X POST https://scribe.whizztech.ai/v1/webhooks \
  -H "Authorization: Bearer $SCRIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.your-app.com/hooks/scribe",
    "events": ["job.succeeded", "job.failed"]
  }'

Response · 201 Created

{
  "id": "a4f81c2d-6e93-40b7-95d2-3c08e7b1f649",
  "object": "webhook_endpoint",
  "url": "https://api.your-app.com/hooks/scribe",
  "events": ["job.succeeded", "job.failed"],
  "secret": "whsec_Zks3JprXcO1FaK9yTqR2v8wBnE5dLmHu"
}

Secret — shown onceThe whsec_ signing secret appears only in this creation response. Store it next to your API key; you need it to verify every delivery. Listing endpoints later does not return it.

GET/v1/webhooks

Response · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "a4f81c2d-6e93-40b7-95d2-3c08e7b1f649",
      "url": "https://api.your-app.com/hooks/scribe",
      "events": ["job.succeeded", "job.failed"],
      "active": true,
      "created_at": "2026-07-06T10:02:31.000Z"
    }
  ]
}

Endpoints are managed (deactivated, inspected, deliveries reviewed) at Dashboard → Webhooks. Inactive endpoints receive nothing.

Event catalog#

Field	Type	Description
job.succeeded	event	Any job (article generation or source ingestion) finished successfully. data carries the job payload including result.
job.failed	event	A job failed. data.error explains; charged credits were refunded before this event fired.

The body is { event, data } where data is the job payload — the job resource minus the stages detail:

Delivery

POST /hooks/scribe HTTP/1.1
Content-Type: application/json
webhook-id: 7c2f4e91-0b5d-4a68-93e1-d8f60a2c47b5
webhook-timestamp: 1751795103
webhook-signature: v1,K6mQxNvB2rTz8wYpL0dHc4jFgS7aEuXiOn9kM3sRq1U=

{
  "event": "job.succeeded",
  "data": {
    "id": "4d1a8f36-9e02-47b8-b7c4-3a92d5e60f18",
    "type": "article",
    "status": "succeeded",
    "result": {
      "article_id": "9e72c4b0-51af-4c3d-8e6a-2d94b7f01c55",
      "title": "SaaS Churn Drops When You Instrument These 5 Moments",
      "word_count": 1584,
      "quality_score": 86,
      "citations": 9
    },
    "error": null,
    "credits_charged": 10,
    "created_at": "2026-07-06T09:41:12.000Z",
    "finished_at": "2026-07-06T09:45:03.000Z"
  }
}

Delivery semantics#

Events go to every active endpoint subscribed to that event type.
Your endpoint has 10 seconds to respond. Any 2xx counts as delivered; anything else — or a timeout — records the delivery as failed with the status code and error.
Three attempts per event. A failed delivery retries after ~30 seconds, then again after ~5 minutes; after the third failure it is marked dead. A retried delivery re-signs with a fresh webhook-timestamp. Still treat polling as the source of truth: on any gap, re-fetch GET /v1/jobs/{id}. Delivery history is visible in the dashboard.
Ack fast: return 200 immediately and process the event on a queue. Slow handlers are the top cause of missed deliveries.
Deliveries can arrive out of order relative to your own API reads — always key your logic off data.id and data.status, not arrival order.

Signature verification#

Every delivery carries three headers:

Field	Type	Description
webhook-id	string	Unique delivery ID. Also your idempotency key for deduping.
webhook-timestamp	string	Unix seconds when the delivery was signed.
webhook-signature	string	`v1,<base64 MAC>` — HMAC-SHA256 over the signed content.

The scheme, exactly:

Key: strip the whsec_ prefix from your secret and base64-decode the remainder. The decoded bytes are the HMAC key — do not use the secret string directly.
Signed content: the string {webhook-id}.{webhook-timestamp}.{raw body} — the three values joined with periods, using the raw request body exactly as received.
Signature: "v1," + base64(HMAC-SHA256(key, signed content)). Compare against the header in constant time, and reject timestamps outside a small tolerance window (5 minutes is standard) to block replays.

Node#

verify.mjs

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

/**
 * Verify a Whizz Scribe webhook (Standard Webhooks scheme).
 * payload must be the RAW request body string — not re-serialized JSON.
 */
export function verifyScribeWebhook(payload, headers, secret, toleranceSec = 300) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];
  if (!id || !timestamp || !signature) return false;

  // reject stale or future-dated deliveries (replay protection)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false;

  // key = base64-decoded secret without the whsec_ prefix
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const signedContent = id + "." + timestamp + "." + payload;
  const expected =
    "v1," + createHmac("sha256", key).update(signedContent).digest("base64");

  // the header may carry multiple space-delimited signatures; ours sends one
  return signature.split(" ").some((candidate) => {
    const a = Buffer.from(candidate);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

// Express example — mount with express.raw() so the body stays untouched:
// app.post("/hooks/scribe", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyScribeWebhook(req.body.toString("utf8"), req.headers, process.env.SCRIBE_WEBHOOK_SECRET)) {
//     return res.status(401).end();
//   }
//   const { event, data } = JSON.parse(req.body.toString("utf8"));
//   res.status(200).end(); // ack fast, process async
// });

Python#

verify.py

import base64
import hashlib
import hmac
import time


def verify_scribe_webhook(payload: bytes, headers: dict, secret: str, tolerance_sec: int = 300) -> bool:
    """payload must be the RAW request body bytes — not re-serialized JSON."""
    wid = headers.get("webhook-id")
    ts = headers.get("webhook-timestamp")
    sig = headers.get("webhook-signature")
    if not (wid and ts and sig):
        return False

    # reject stale or future-dated deliveries (replay protection)
    if abs(time.time() - int(ts)) > tolerance_sec:
        return False

    # key = base64-decoded secret without the whsec_ prefix
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed_content = f"{wid}.{ts}.".encode() + payload
    digest = hmac.new(key, signed_content, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()

    # the header may carry multiple space-delimited signatures; ours sends one
    return any(hmac.compare_digest(candidate, expected) for candidate in sig.split(" "))

The SDK exports this exact check as verifyWebhookSignature(payload, headers, secret) — Web Crypto based, so it runs in Node 18+ and edge runtimes.

NextUsage→