Events

Every state change you act on is appended to one durable per-org log. Webhooks and 2 server-sent event streams carry it.

Each event is an envelope { id, type, seq, createdAt, data }. seq is the row's creation time in milliseconds, so it increases within an org, is not dense and can be fractional: order by it, dedupe by id.

Webhook delivery

A delivery is a POST of the envelope with Belora-Event, Belora-Delivery and Belora-Signature: t=<unix seconds>,v1=<hex>. v1 is the lowercase hex HMAC-SHA256, keyed with the endpoint secret, of t + "." + raw body. Reject a t more than 300 seconds from your clock.

signal.clustered

A signal was clustered into a theme

data

signalId	string
themeId	string

decision.created

A decision was opened and awaits a person

data

decisionId	string
themeId	string
question	string
options	string[]

decision.resolved

A decision received its verdict

data

decisionId	string
themeId	string
chosenIndex	integer
option	string	The label of the chosen option
rationale	string
decidedBy	string	The person who decided: an auth id for the console and API doors, a Slack user id for Slack, Belora for an auto-applied decision
door	"api" \| "console" \| "slack"	Which surface carried the verdict

job.created

A job was queued for a runner to claim

data

jobId	string
repo	string	The repository the job targets, as owner/name
decisionId	string \| null	The decision the job implements; null when it follows a theme
linkedJobIds	string[]	Jobs already queued for the same decision, claimed together across repositories

job.completed

A job closed with a recap; the grade is what its pull request said at that moment

data

jobId	string
themeId	string \| null
grade	object \| null	Null when the closer is not an executor kind that is graded

job.failed

A job failed for good: the retry cap, a closing that never finished, or a claim too large to run

data

jobId	string
themeId	string \| null
reason	string

theme.shipped

A theme shipped: every pull request it recorded is merged

data

themeId	string
title	string
prs	object[]
prs[].repo	string	owner/name
prs[].number	integer
prs[].url	string
changed	string[]	One line per changed file from the recaps of the theme's jobs, as path: what
recapSynthesized	boolean	Belora wrote at least one of those recaps from the diff because the executor sent none

theme.merged

A theme was merged into another and archived

data

themeId	string	The theme that was absorbed
intoThemeId	string

decision.escalated

An unanswered decision, or the question of a paused job, was nudged to its owner or re-routed to the org owner

data

decisionId	string \| null	The decision; null when a paused job's question escalated
jobId	string \| null	The paused job; null when a decision escalated
step	"nudge" \| "reroute"
to	string \| null	The person addressed; null when a nudge has nobody with a verified identity to reach

job.expired

A job lost its lease or stalled in closing, and was requeued or failed

data

jobId	string
outcome	"requeued" \| "failed"
reason	"lease" \| "closing"
attempts	integer
personId	string \| null	The person whose API key held the job; null for the runner

Streams

GET /v1/events/stream

Server-sent events of the org's event log, resumable with Last-Event-ID; a stream lasts at most 280 seconds, so reconnect

signal.clustereddecision.createddecision.resolvedjob.createdjob.completedjob.failedtheme.shippedtheme.mergeddecision.escalatedjob.expired

GET /v1/sessions/{id}/events

Server-sent events of one session's messages and commit, resumable with Last-Event-ID; a stream lasts at most 280 seconds, so reconnect

session.messagesession.commitsession.concluded