Webhooks

Get notified the moment long-running work finishes, instead of polling. Subscribe an HTTPS endpoint to consultation.* and batch.* events.

Events

Register an endpoint

post /v1/webhooks

curl -X POST https://api.niah.si/v1/webhooks \
  -H "Authorization: Bearer $NIAH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/niah",
    "events": ["consultation.completed", "batch.completed"],
    "description": "Prod pipeline"
  }'

Verify signatures

Every delivery is signed with an HMAC-SHA256 of the raw request body using your webhook secret, sent in the X-Niah-Signature header. Recompute it and compare with a constant-time check before trusting the payload.

import hashlib, hmac

def valid(secret: str, raw_body: bytes, header_sig: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_sig)

Delivery & retries

Respond with a 2xx quickly (do heavy work asynchronously). Niah retries failed deliveries with backoff. Inspect the full delivery history — status codes, errors, and timing — at:

get /v1/webhooks/deliveries

Manage