Webhooks

OnePath sends webhook events to your registered endpoints when key actions happen — user health data updates, AI analysis completion, consent changes, and more.

Registering an Endpoint

Register endpoints in the Partner Portal under Settings → Webhooks.

Requirements:

• Must be HTTPS
• Must return 200 within 5 seconds
• Must verify the X-Onepath-Signature header

Event Types

Payload Structure

{
  "id": "evt_01j2k3l4m5n6",
  "type": "lab_analysis.complete",
  "createdAt": "2026-08-04T09:01:45Z",
  "data": {
    "userId": "onepath_usr_7xkm2p9q",
    "analysisId": "anlz_abc123"
  }
}

Verifying Signatures

Always verify the X-Onepath-Signature header to confirm events are from OnePath:

import { createHmac } from "crypto";

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

Retry Policy

Failed deliveries (non-200 response or timeout) are retried with exponential backoff:

After 5 failures, the event is marked as failed and logged in the Partner Portal.