Receive and verify webhooks

The draft uses Standard Webhooks headers and at-least-once delivery. Registration, secret rotation and replay tooling must be verified before live integration.

Register the destination

POST /webhook-endpoints registers an HTTPS URL and selected event types. webhooks:manage is required. Store the returned signing secret once in backend secret storage; never ship it to a mobile app.

Events are thin: identifiers and status tell you what to retrieve through the authorized API. They do not include observation values or transcripts. An export.ready notification carries an operation ID, not a bearer download link.

Verify before processing

Use the unchanged raw request body. Verify all three headers: webhook-id, webhook-timestamp and webhook-signature. Reject stale or implausibly future delivery timestamps. The ID is stable across retries, while the signature timestamp describes the delivery attempt.

The following TypeScript example implements HMAC verification for the Standard Webhooks secret encoding. It is an illustrative receiver helper, not a claim of a published ENO SDK.

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

export function verifyWebhook(
  rawBody: Buffer,
  headers: Record<string, string | undefined>,
  secrets: string[],
  nowSeconds = Math.floor(Date.now() / 1000),
): string {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !/^\d+$/.test(timestamp) || !signatures) {
    throw new Error('Missing or invalid signature headers');
  }
  if (Math.abs(nowSeconds - Number(timestamp)) > 300) {
    throw new Error('Webhook timestamp outside tolerance');
  }
  const candidates = signatures.split(/\s+/).flatMap((entry) => {
    const [version, value] = entry.split(',');
    return version === 'v1' && value ? [Buffer.from(value, 'base64')] : [];
  });
  for (const secret of secrets) {
    const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
    const expected = createHmac('sha256', key)
      .update(`${id}.${timestamp}.`)
      .update(rawBody)
      .digest();
    if (candidates.some((value) => value.length === expected.length && timingSafeEqual(value, expected))) {
      return id;
    }
  }
  throw new Error('Invalid webhook signature');
}

Use both old and new secrets during an agreed rotation overlap. The draft still needs a management endpoint for rotation; signature compatibility alone does not implement it.

Acknowledge durably and deduplicate

After verification, atomically deduplicate the webhook ID and enqueue the event in your durable inbox. Return 2xx promptly after that durable acceptance. Process the event asynchronously. Do not acknowledge an event you would lose on process restart.

The draft retries non-2xx responses for up to 72 hours. Do not depend on delivery order. Re-fetch the resource and compare source revision or operation state before changing your local view.

Recover after a missed event

Poll document processing status, immutable source contributions or GET /operations/{operationId} using the saved IDs. Patient authorization is checked when the resource is fetched; receiving an event does not confer access.

Standard Webhooks specification

Partner API 0.1.0-draft.3 · Draft contract · Sandbox and SDK availability require confirmation.