Skip to main content

Integration guide

Webhooks (outbound subscriptions)

Create webhook subscriptions, verify signatures, and inspect delivery history.

Field-level detail for every endpoint is in the API reference.

Register HTTPS callbacks for lifecycle events. The signing secret is returned once, on create.

Endpoints

MethodPathPurpose
POST/v1/webhooks/subscriptionsCreate subscription (returns secret once)
GET/v1/webhooks/subscriptionsList active (no secrets)
DELETE/v1/webhooks/subscriptions/{subscription_id}Deactivate
GET/v1/webhooks/deliveriesRecent delivery attempts

URL rules (SSRF)

  • Scheme must be https
  • Hostname must be an FQDN (contains .)
  • Private / reserved IP literals rejected

Events

Subscribable set (also * wildcard) includes:

  • document.status_changed, document.uploaded, document.completed
  • adjudication.case_created, adjudication.case_resolved
  • intake.submitted, intake.batch_submitted
  • scorecard.created

See the event enum in the OpenAPI integrator subset.

Signing contract

ItemValue
HeaderX-QueryTek-Review-Signature
AlgorithmHMAC-SHA256, hex digest
Signed bytesRaw HTTP body
Canonical JSONPlatform uses json.dumps(..., sort_keys=True) when building the body

Store the secret from the create response immediately — it is not returned on list.

Verify sample

import hashlib
import hmac


def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Compute the digest over the raw request bytes before any JSON parsing.

Delivery status (live)

Outbound delivery is live: each matching lifecycle event is POSTed as a signed HTTPS payload to your subscription URL, with up to 3 attempts and increasing delay between retries. Poll GET /v1/webhooks/deliveries for attempt history (pending, delivered, failed). Implement signature verification against this contract before go-live.

Payload envelope (intended)

{
  "event": "document.status_changed",
  "tenant_id": "<uuid>",
  "timestamp": "<iso8601>",
  "data": { }
}

Payloads carry IDs/status metadata — not document plaintext.