Webhooks

Webhook endpoints receive a JSON notification each time a subscribed event happens in your organization, such as a case update, a finished document job, or a completed export. Instead of polling, your server listens for these deliveries. Paths are relative to /api/v1.

Endpoints

Event types

Subscribe to exact event types or use a pattern:

• * receives every event.
• case.* receives every event whose type starts with case. (the same works for document.*, export.*, user.*, and role.*).

Delivery format

Each delivery is an HTTPS POST with a CloudEvents 1.0 JSON body (Content-Type: application/cloudevents+json). Payloads are minimal: they identify the resource and never include file contents, OCR text, or secrets. Fetch the full resource through the API when you need more detail.

{
  "specversion": "1.0",
  "id": "evt_01J...",
  "source": "https://redactstripe/organizations/{organization_id}",
  "type": "export.completed",
  "subject": "exports/exp_...",
  "time": "2026-10-13T10:15:00.000Z",
  "datacontenttype": "application/json",
  "data": {
    "object": { "id": "exp_...", "object": "export" },
    "links": { "resource": "/v1/exports/exp_..." }
  }
}

Headers

Verifying a signature (planned scheme)

When signatures are available, the signed content is the Unix time in seconds from the timestamp, a period, and the raw request body. The expected value is v1= plus the hex HMAC-SHA-256 of that content using the endpoint secret. Reject deliveries whose timestamp is more than five minutes old or in the future, and compare signatures in constant time.

import crypto from "node:crypto";

export function verifyDelivery(rawBody, headers, secret) {
  const ts = Math.floor(Date.parse(headers["x-redactstripe-timestamp"]) / 1000);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;

  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`, "utf8")
    .digest("hex");
  const received = headers["x-redactstripe-signature"] || "";
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Responses and retries

• Respond with any 2xx status within 10 seconds to acknowledge a delivery. Anything slower counts as a timeout.
• Timeouts, network errors, 408, 429, and 5xx responses are treated as retryable. Other 4xx responses are not retried.
• Each endpoint has a health_score that drops when deliveries fail.
• Deliveries can be read and replayed manually, described below.

Deliveries