Get signed events delivered to your endpoint when state changes.
Subscribe to QorTrace state changes — audits delivered, scans scored, Atlas alerts.
Available events
audit.queuedaudit.deliveredaudit.failedscan.completedatlas.alert.fired(Tier escalation, score drift, etc.)atlas.wallet.addedaccount.plan.changed
Full schema for each event lives at /docs/sdk-reference#webhooks.
Creating a subscription
Account → Webhooks → + New subscription:
- URL — your endpoint (must be HTTPS)
- Events — pick which ones to receive
- Description — for your own reference
- Active — toggle on
We POST a JSON payload to your URL within a few seconds of each event.
Signature verification
Every webhook is signed. Verify the X-QorTrace-Signature header against your subscription's signing secret:
import hmac, hashlib
def verify(secret: str, body: bytes, signature: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
Reject any request where the signature doesn't match. We never retry a failed-verification request.
Retries
If your endpoint returns non-2xx, we retry with exponential backoff:
- 1 min
- 5 min
- 30 min
- 2 hours
- 12 hours
After 5 failures we mark the subscription unhealthy and email the Owner. Re-enable from Account → Webhooks → subscription detail → Re-enable once you've fixed the issue.
Replay
Any delivery (success or failure) can be replayed manually from Account → Webhooks → subscription detail → Deliveries → click any → Replay. Useful for testing.
Idempotency
Every event includes an event.id. Use it as your idempotency key — we may deliver the same event more than once (rare, but possible during retries near our SLA boundary).
Test mode
Want to test your handler without waiting for real events? Click Send test event — we POST a synthetic event with the same shape as the real one. It includes a test: true flag so your handler can branch.