Risk push integration
Korala can notify your backend when risk evidence, assessments, tasks or overrides change. Your backend does not need to poll continuously to discover these changes. Use the notification as a reason to read current state, then apply your own account or payment authorization rules.
Connect an endpoint
In Settings → Webhooks, create an endpoint, select the Risk events you need,
and choose Test or Live. Alternatively, call POST /api/v1/webhooks with
url, events and mode. API-key subscriptions are pinned to the key’s environment.
Keep the returned signing secret on your server; it is not an API key.
| Event | What changed |
|---|---|
risk.context.policies_configured | The pinned policy versions for a context changed. |
risk.subject.created | A durable subject was registered. |
risk.policy.created / risk.policy.published | A policy version was created or published. |
risk.activity.reported | An integration recorded reported activity. |
risk.evidence.recorded | Evidence was received, superseded or revoked. |
risk.evidence.batch_recorded | A batch of evidence receipts committed for one subject. |
risk.assessment.created | An assessment and its snapshot were committed. |
risk.action.requested / risk.action.transitioned | A requirement was created or its status changed. |
risk.override.created / risk.override.revoked | A reviewer decision was recorded or revoked. |
Only active, same-organization, same-environment subscriptions present when the change commits receive deliveries. Adding a subscription does not replay older history. Seed your initial view through the risk APIs, then use push notifications and occasional reconciliation to maintain it.
Payload and authentication
A notification contains resource references. It does not copy evidence values, customer names, policy rules or reviewer reasons into the payload.
{
"eventId": "11111111-1111-4111-8111-111111111111",
"event": "risk.assessment.created",
"timestamp": "2026-09-28T10:00:00.000Z",
"data": {
"organizationId": "22222222-2222-4222-8222-222222222222",
"subjectId": "33333333-3333-4333-8333-333333333333",
"resourceId": "44444444-4444-4444-8444-444444444444",
"sandbox": true
}
}eventId is the persisted risk event ID. It stays the same across retries and
subscribers. resourceId identifies the changed subject, policy, event, evidence,
assessment, action or override according to the event type. Policy notifications
and context configuration notifications have subjectId: null. For
risk.context.policies_configured, resourceId identifies the context; read
GET /api/v1/risk/contexts/{resourceId}/policies for its current pins. For risk.evidence.batch_recorded, eventId and
resourceId identify the batch. Read GET /api/v1/risk/events/{eventId} to
obtain its ordered data.detail.evidenceIds, then read the evidence receipts.
A batch also emits individual receipt events if you subscribe to them.
Use the original request bytes with verifyWebhookSignature from @korala/auth:
const valid = verifyWebhookSignature(
rawBody,
request.headers['x-timestamp'],
request.headers['x-signature'],
webhookSecret,
);Verify before parsing or processing. Check the signed body’s event, organization
and data.sandbox against your configured connection. The timestamp verification
rejects signatures outside the allowed time window. Do not authorize using the
X-Webhook-Event header alone; compare it with the signed body.
In production, commit a deduplicated event to a durable inbox before returning a
2xx response, then reconcile asynchronously. Acknowledge duplicates successfully.
Use (connection, eventId) as an inbox key and serialize updates for each subject
or otherwise prevent an older reconciliation from overwriting a newer one.
Reconcile current risk
For risk.assessment.created, read
GET /api/v1/risk/assessments/{resourceId}/state. For evidence, activity, action or
override notifications, locate the subject’s latest assessment for each policy
purpose and read its state. Follow every nextOffset when listing history.
A completed collection task does not clear a review decision. New evidence can
make the earlier result stale before a replacement assessment exists. Respect
current, effectiveDecision, evidence freshness, review deadlines and override
expiry. none means no restriction under that policy, not blanket authorization.
Push events report committed changes. Monitored policies produce new assessments after evidence expiry or a review deadline, then emit assessment events. Unmonitored assessments and override expiry alone do not emit notifications. Clients must still enforce recorded deadlines.
Delivery behavior
Korala records risk changes and pending notifications together, then delivers notifications in the background. Processing backlogs and service interruptions can delay delivery. Korala makes five delivery attempts with exponential backoff starting at 60 seconds and a ten-second request timeout. You can inspect failed deliveries and retry them from Settings → Webhooks or the retry API.
Delivery is at-least-once, not exactly-once, and ordering is not guaranteed. Deduplicate even after a successful response: a process can stop after your handler commits but before Korala records delivery success. Test records are sent only to test subscriptions; mode is immutable on an existing subscription.
Test your webhook connection
Create a test-mode subscription, submit a fictional subject and evidence through
the test API, and request an assessment. Confirm that your receiver verifies the
signature, stores eventId for deduplication and fetches current state before
acting. Then replace the evidence and verify that your receiver reconciles the
new assessment and any open actions. Keep test and live subscriptions separate.
Paging delivery history
Treat nextCursor as opaque and pass it unchanged when requesting the next page
for the same webhook and workspace mode. New cursors preserve deliveries with
identical creation timestamps. Legacy timestamp cursors remain accepted during
client upgrades. Invalid cursors and non-positive or non-integer limits return
HTTP 400; page size is capped at 100.