README — staff webhook delivery

An owner can register up to five staff webhook endpoints through the Admin hooks API. Delivery is an outbound HTTPS POST to the registered URL, not an inbound Handwrite route or a WebSocket. This contract is separate from regular-account document webhooks. Keep the receiver and its signing secret within the authorized staff integration.

Categories and body

Category	Events
security	Denied sign-ins/step-ups, staff identity/role changes, configuration/hook changes and qualifying denied or failed actions.
access	Customer or school access restrictions/restoration, credential revocation and organisation API blocking.
user	Customer name/email changes, deletion requests and restoration.
retention	Holds, purges, school closure, export and erasure actions.
data_access	Audited viewing of private customer metadata/content fields and attachment downloads; potentially high volume.

An event can have multiple categories. type is staff. plus the first category in the defined category order; use categories to inspect every match. Routine desk work and rollups do not necessarily produce a staff webhook. Test delivery uses staff.security, action hooks.test, audit ID test and sequence zero.

type StaffHookEvent = {
  id: string;
  type: `staff.${"security" | "access" | "user" | "retention" | "data_access"}`;
  categories: string[];
  created: string;
  data: {
    action: string;
    outcome: string;
    actor: { sub: string; role: string };
    target: { type: string; id: string };
    at: string;
    audit: { id: string; seq: number };
  };
};

Payloads contain action/actor/target identifiers and audit position, not the audit reason, before/after values, names, emails or document text. Treat identifiers as internal information. created is event creation time; data.at is the audit entry time. The sequence can support reconciliation but does not establish delivery ordering.

Authentication and acknowledgement

The sender uses Content-Type: application/json, User-Agent: Handwrite-Staff-Webhooks/1.0, Handwrite-Event-Id, Handwrite-Event-Type and Handwrite-Signature. The signature is t=<Unix seconds>,v1=<hex HMAC-SHA256> over the exact <timestamp>.<raw body> string using the endpoint's secret. Verify the raw request bytes before parsing/re-serializing JSON, use a constant-time comparison, and apply a receiver timestamp/replay policy. The secret is revealed once by hook creation; it is not a staff session or a personal developer token.

Return a 2xx response within the ten-second delivery timeout. Other status codes and transport failures retry. Delivery resolves and pins a permitted public HTTPS address and does not follow an untrusted redirect to a private host.

Retries and reconciliation

There are up to eight attempts in total, with backoff beginning at one minute and doubling toward roughly an hour; exhausted messages go to the configured dead-letter queue. Store event IDs to make receiver processing idempotent. Return success for an already processed event. Do not assume exactly-once or ordered delivery.

Webhook queuing must not fail the originating audit write. An unavailable queue or queue failure can therefore leave an audit event without a delivered webhook: reconcile important workflows against the authorized audit interface. A deleted endpoint or one that no longer subscribes to any event category is skipped. Endpoint registration data is cached for up to one minute per process, and the worker rechecks subscription at delivery. Console fields report the last delivery time, outcome, HTTP status and error.

Source: shared/staff-hooks.ts, shared/staff-hook-categories.ts, admin/src/jobs/staff-hooks.ts, admin/src/admin/staff-hooks-admin.ts, and src/cloud/webhooks.ts. This is the source-derived receiver contract; no live delivery was sent during this documentation task.

README — staff webhook delivery

Categories and body#

Authentication and acknowledgement#

Retries and reconciliation#

Categories and body

Authentication and acknowledgement

Retries and reconciliation