Webhooks

Inbound clinical events with HMAC verification, delivery IDs, retry backoff, and replay.

The Hebrah API delivers signed HTTP POSTs to your receiver. Configure a default webhook URL in dashboard Settings, then override per connection when needed. Every outbound delivery includes X-Hebrah-Delivery-Id for idempotent handling.

Two-tier configuration

Organization default: URL and signing secret in Settings
Connection override: optional per-connection URL/secret on the Test tab
Effective values: connection override wins when set

Reliability

Retry queue: exponential backoff (30s → 2m → 10m → 30m), up to 4 attempts
Stored envelopes: replay failed deliveries from the control plane or dashboard
Delivery history: list attempts on the connection Test tab
Chaos profiles: PATCH /v1/sandbox/webhook-reliability for transient 503, slow, rate-limit modes (with webhook-relay-demo on :3004)

Verify signatures

Hebrah signs the raw request body with HMAC-SHA256. Compare against the X-Hebrah-Signature header using your webhook secret.

const signature = request.headers['x-hebrah-signature']
const deliveryId = request.headers['x-hebrah-delivery-id']
const expected = hmacSha256(rawBody, webhookSecret) // hbsec_*
// timing-safe compare; dedupe on deliveryId

@hebrah/sdk v0.5 (Node.js)

import { verifyWebhookSignature } from '@hebrah/sdk'

const payload = verifyWebhookSignature(
  rawBody,
  req.headers['x-hebrah-signature'],
  process.env.HEBRAH_WEBHOOK_SECRET! // hbsec_*
)

// List and replay from control plane
const deliveries = await client.webhooks.listDeliveries()
await client.webhooks.replayDelivery(deliveryId)

Hebrah Python SDK (coming soon)

from hebrah import verify_webhook_signature

payload = verify_webhook_signature(
    request.get_data(),
    request.headers.get('X-Hebrah-Signature'),
    webhook_secret,  # hbsec_*
)

Trigger a mock event

During onboarding or from the connection Test tab, call POST /v1/webhooks/trigger-mock-event with optional scenario_id and connection_id.

Payload shape

Envelopes include event, connection_id, environment, and a synthetic FHIR resource. Domain events span clinical ADT through prior auth, claims, eligibility, and webhook reliability observability. See the Sandbox guide.