Ehr agent webhook

Sent to your webhook URL when EHR Agent analysis is complete (success or error).

Webhook Delivery:

• Webhooks are delivered via HTTP POST to the webhookUrl you provide in your request
• We retry failed deliveries up to 3 times with exponential backoff (immediate, 5s, 15s delays)
• Your endpoint should return a 2xx status code within 30 seconds to acknowledge receipt
• If all retries fail, the webhook is logged but not redelivered

Webhook Security: All webhooks are signed with HMAC-SHA256 using your company’s webhook secret. You must verify the signature to ensure authenticity.

Webhook Headers:

• X-Helios-Signature: HMAC-SHA256 signature in format sha256=<hex>
• X-Helios-Timestamp: Unix timestamp (seconds) when webhook was sent
• X-Helios-Run-ID: The unique run ID for this analysis

Signature Verification:

1. Get the raw request body (as string, before JSON parsing)
2. Check timestamp is recent (within 5 minutes) to prevent replay attacks
3. Compute expected signature: sha256=HMAC-SHA256(webhook_secret, raw_body)
4. Compare signatures using timing-safe comparison

Example Verification (Node.js):

import { createHmac, timingSafeEqual } from 'crypto'

function verifyWebhook(rawBody: string, signature: string, timestamp: string, webhookSecret: string): boolean {
  // Check timestamp is recent (within 5 minutes)
  const now = Math.floor(Date.now() / 1000)
  const webhookTime = parseInt(timestamp, 10)
  if (Math.abs(now - webhookTime) > 300) {
    return false
  }

  // Compute expected signature
  const expected = 'sha256=' + createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex')

  // Timing-safe comparison
  if (expected.length !== signature.length) return false
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

See full documentation at: https://docs.heliosai.health/webhooks