Webhooks
HMAC signing for outbound results and inbound submissions, with known-good test vectors
Aletheia's outbound result webhook is generic: any tenant that registers a callback URL
and an outbound HMAC secret receives HMAC-signed deliveries with X-Forensic-Signature.
Aletheia's inbound URL-fetch webhook is the push-style intake surface (see
Submitting a case):
a tenant enrolled for inbound push signs its POSTs with X-Inbound-Signature.
Both directions use HMAC-SHA256, emitted and verified as lowercase hexadecimal with
no prefix (no sha256=), computed over the exact raw bytes of the request body, not a
re-serialized or canonicalised form.
| Direction | Header | Who signs | Secret |
|---|---|---|---|
| Outbound, Aletheia to tenant | X-Forensic-Signature | Aletheia | outbound webhook secret |
| Inbound, tenant to Aletheia | X-Inbound-Signature | The tenant | inbound webhook secret |
The two secrets are different and are both provisioned at onboarding, see Sandbox.
Verification is constant-time on both sides. The inbound check lowercases the received header
before comparison, so an uppercase-hex inbound signature is also accepted, but emit lowercase
hex for forward-compatibility. Base64 and sha256=-prefixed forms are not accepted.
Sign and verify the exact bytes on the wire. Do not pretty-print, re-key-order, or re-encode the
JSON before hashing. On the receiving side, capture the raw body and HMAC that, distinct from the
parsed JSON; most web frameworks expose it (request.body(), req.rawBody).
Inbound: X-Inbound-Signature (you sign, Aletheia verifies)
X-Inbound-Signature = lowercase_hex( HMAC_SHA256( inbound_webhook_secret, raw_request_body ) )Known-good vector:
secret : whsec_demo_inbound_0123456789abcdef
body (289 bytes, exactly):
{"event_type":"applicant_submitted","external_applicant_id":"APP-2026-000123","submitted_at":"2026-09-15T08:30:00Z","applicant":{"name":"Max Mustermann","iban":"AT611904300234573201","dob":"1985-03-12"},"documents":[{"type":"id_front","url":"https://docs.example/doc1","sha256":"aabbcc"}]}
X-Inbound-Signature : da422f245d81006a4e2a829cb03ca818393b0168c8516f7f9a06a29bbd80e4e7If your HMAC of the body bytes above with that secret does not equal the signature, your client is not byte-identical to what you will transmit; fix the serialization before sending live traffic.
Outbound: X-Forensic-Signature (Aletheia signs, you verify)
X-Forensic-Signature = lowercase_hex( HMAC_SHA256( outbound_webhook_secret, raw_request_body ) )Aletheia serializes the outbound body with the equivalent of Python json.dumps(payload, default=str), that is a space after every : and ,. Verify against the exact bytes you
receive; do not re-serialize.
Known-good vector:
secret : whsec_demo_outbound_fedcba9876543210
body (489 bytes, exactly; note the spaces after ':' and ','):
{"event_type": "analysis_completed", "event_id": "evt_2f1c9a40-0000-4000-8000-000000000001", "external_applicant_id": "APP-2026-000123", "internal_applicant_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "verdict": "ESCALATE", "score": 42, "top_findings": [{"code": "KAZ_BACKDATING", "severity": "high", "summary": "Bank statement creation date precedes stated period by 14 days"}], "audit_reference": "8821", "analyzed_at": "2026-09-15T08:31:42Z", "event_timestamp": "2026-09-15T08:31:43Z"}
X-Forensic-Signature : 89269bc2b59d090324d48c8a52e202c8590a09c367de8c13543a7af3db625ed8The same signed body is replayed on each delivery attempt, so the signature is stable across retries. The body fields are described under Outbound result webhook.
Reference verifier (Python)
import hashlib, hmac
def verify(secret: str, raw_body: bytes, received_sig: str) -> bool:
expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_sig.strip().lower())Reference verifier (Node.js)
const crypto = require('crypto');
function verify(secret, rawBody, receivedSig) {
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(receivedSig.trim().toLowerCase());
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Outbound deliveries are made only once the outbound secret is provisioned for your tenant; until then no callback is sent. See also Guides / Webhooks for the cross-service overview.