| # Webhooks |
|
|
| Superlog sends webhooks to your server when interesting things happen in a |
| project. Today we ship exactly one event: |
|
|
| | Event | Fires when | |
| | ---------------------- | ------------------------------------------------------------------------------------------- | |
| | `agent_run.completed` | An agent run on an incident finishes with findings — either a PR was opened, or the agent reached a no-PR conclusion (noise / already resolved / PR policy = never). Not fired when an agent run is closed because its incident was merged into a duplicate. | |
|
|
| > **Breaking change (May 2026):** the event name was renamed from |
| > `investigation.completed` to `agent_run.completed` as part of merging the |
| > incident and investigation concepts. Existing endpoints' `enabled_events` |
| > are migrated automatically; update any client-side switch / filter on the |
| > event name to match. |
|
|
| ## Configuring an endpoint |
|
|
| Go to **Settings → Webhooks** for the project that should send the event. |
|
|
| 1. Paste your endpoint URL (`https://...`). |
| 2. Click **Add endpoint**. Superlog generates a signing secret prefixed `whsec_` |
| and shows it to you once. Copy it — we never display it again. |
| 3. Use **Send test** to fire a sample payload right away. The delivery shows up |
| in the live log under the endpoint. |
|
|
| You can rotate the secret at any time, disable an endpoint (deliveries are |
| suspended but state is preserved), or delete it (deletes all delivery history). |
|
|
| ## Delivery semantics |
|
|
| - Each event is sent as `POST` with `Content-Type: application/json`. |
| - Request timeout is **10 seconds**. Anything slower is treated as a failure |
| and retried. |
| - Non-2xx responses and connection errors / timeouts are retried with backoff |
| before attempts 2-8: **30s → 1m → 2m → 5m → 15m → 1h → 6h** (no wait before |
| attempt 1). After 8 failed attempts (~8h elapsed) the delivery is marked |
| `failed` and we stop trying. |
| - Automatic retries reuse the same `Superlog-Delivery` id — use it as your |
| idempotency key. A manual **redeliver** from Settings enqueues a *new* |
| delivery row with a *new* id; if you redeliver something we already |
| delivered, your receiver will see it twice. |
| - Disabling an endpoint stops new deliveries from being enqueued, and any |
| deliveries still pending at the time the endpoint is disabled are marked |
| `failed` with `lastError = "endpoint disabled"` on the next worker tick. |
| - Deliveries appear under the endpoint in Settings with status, last HTTP code, |
| response body (truncated to 2 KiB), next attempt, and any error. |
| - The **Send test** button posts a stub payload of the form |
| `{ event, eventId, occurredAt, test: true, message, project }` — it shares |
| transport, signature, and retry behavior with real events but does not |
| include `agentRun`, `incident`, `events`, `pullRequests`, or |
| `linearTickets`. Use it to verify transport and signature only. |
|
|
| ## Signing |
|
|
| Every request has a `Superlog-Signature` header in Stripe-style format: |
|
|
| ``` |
| Superlog-Signature: t=1715450000,v1=<hex> |
| ``` |
|
|
| `<hex>` is `HMAC_SHA256(secret, "<t>.<rawRequestBody>")`. |
|
|
| Verify in your handler: |
|
|
| ```ts |
| import { createHmac, timingSafeEqual } from "node:crypto"; |
| |
| function verify(secret: string, header: string, rawBody: string): boolean { |
| const parts = Object.fromEntries( |
| header.split(",").map((p) => { |
| const i = p.indexOf("="); |
| return [p.slice(0, i), p.slice(i + 1)]; |
| }), |
| ); |
| const ts = Number(parts.t); |
| const v1 = parts.v1; |
| if (!Number.isFinite(ts) || !v1) return false; |
| // Reject anything older than 5 minutes to block replay attacks. |
| if (Math.abs(Math.floor(Date.now() / 1000) - ts) > 300) return false; |
| const expected = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex"); |
| const a = Buffer.from(expected); |
| const b = Buffer.from(v1); |
| return a.length === b.length && timingSafeEqual(a, b); |
| } |
| ``` |
|
|
| Important: verify against the **raw body**, before JSON-parsing. Frameworks |
| that re-stringify JSON will produce a different hash. |
|
|
| ## Headers |
|
|
| | Header | Value | |
| | ----------------------- | ------------------------------------------------------ | |
| | `Superlog-Signature` | `t=<unix-ts>,v1=<hex>` HMAC-SHA256 over `<ts>.<body>` | |
| | `Superlog-Event` | Event type, e.g. `agent_run.completed` | |
| | `Superlog-Delivery` | UUID of this delivery — stable across retries | |
| | `User-Agent` | `Superlog-Webhooks/1.0` | |
|
|
| ## `agent_run.completed` payload |
| |
| ```json |
| { |
| "event": "agent_run.completed", |
| "eventId": "5f0a6b6e-...", |
| "occurredAt": "2026-05-11T12:34:56.000Z", |
| "project": { "id": "uuid", "name": "Default", "slug": "default" }, |
| "agentRun": { |
| "id": "uuid", |
| "state": "complete", |
| "runtime": "anthropic", |
| "completedAt": "2026-05-11T12:34:56.000Z", |
| "startedAt": "2026-05-11T12:20:00.000Z", |
| "cumulativeRuntimeMinutes": 14, |
| "resumeCount": 0, |
| "failureReason": null, |
| "result": { |
| "state": "complete", |
| "summary": "Root cause: missing null check in orders.ts:42", |
| "rootCauseConfidence": "high", |
| "rootCause": { |
| "text": "orders.ts:42 dereferences `customer` without checking for null.", |
| "confidence": 9 |
| }, |
| "estimatedImpact": { |
| "text": "~3% of /api/orders requests since deploy at 11:14 UTC.", |
| "confidence": 7 |
| }, |
| "severity": "SEV-2", |
| "pr": { |
| "selectedRepoFullName": "acme/orders", |
| "branchName": "superlog/fix-orders-typeerror", |
| "baseBranch": "main", |
| "openStatus": "opened", |
| "url": "https://github.com/acme/orders/pull/4271", |
| "patch": "diff --git a/orders.ts ...", |
| "validationPassed": true |
| }, |
| "linearTicket": { |
| "id": "...", |
| "url": "https://linear.app/acme/issue/ENG-1234", |
| "createdByAgent": true |
| }, |
| "noiseClassification": null, |
| "resolutionClassification": null |
| } |
| }, |
| "incident": { |
| "id": "uuid", |
| "title": "TypeError in /api/orders", |
| "codename": "squishy-narwhal", |
| "status": "open", |
| "severity": "SEV-2", |
| "service": "orders", |
| "firstSeen": "2026-05-11T11:00:00.000Z", |
| "lastSeen": "2026-05-11T12:30:00.000Z", |
| "issueCount": 14, |
| "rootCauseText": "orders.ts:42 dereferences `customer` without checking for null.", |
| "rootCauseConfidence": 9, |
| "estimatedImpactText": "~3% of /api/orders requests since deploy at 11:14 UTC.", |
| "estimatedImpactConfidence": 7, |
| "suggestedSeverity": "SEV-2", |
| "noiseClassification": null, |
| "resolutionClassification": null, |
| "findingsAgentRunId": "uuid" |
| }, |
| "events": [ |
| { |
| "id": "uuid", |
| "kind": "agent_run_started", |
| "summary": "...", |
| "detail": { }, |
| "createdAt": "2026-05-11T12:20:00.000Z" |
| } |
| ], |
| "pullRequests": [ |
| { |
| "id": "uuid", |
| "repoFullName": "acme/orders", |
| "prNumber": 4271, |
| "url": "https://github.com/acme/orders/pull/4271", |
| "branchName": "superlog/fix-orders-typeerror", |
| "baseBranch": "main", |
| "state": "open", |
| "title": "[superlog] Fix TypeError in /api/orders", |
| "mergedAt": null, |
| "closedAt": null |
| } |
| ], |
| "linearTickets": [ |
| { |
| "id": "uuid", |
| "workspaceId": "...", |
| "ticketId": "...", |
| "ticketIdentifier": "ENG-1234", |
| "url": "https://linear.app/acme/issue/ENG-1234", |
| "title": "Fix TypeError in /api/orders", |
| "state": "In Progress" |
| } |
| ] |
| } |
| ``` |
| |
| Field notes: |
|
|
| - `agentRun.state` is always `"complete"` for this event. Failed agent runs |
| and runs whose incident was merged into another do not fire a webhook. |
| - `agentRun.failureReason` is always `null` here for the same reason. |
| - `incident.status` is one of `"open" | "resolved" | "autoresolved_noise" | "merged"`. |
| Note that an `agent_run.completed` can fire while the incident is still |
| `"open"` — the agent run finished, but no one has resolved the incident |
| yet. |
| - `incident.severity` and `agentRun.result.severity` are |
| `"SEV-1" | "SEV-2" | "SEV-3" | null`. The incident's `suggestedSeverity` |
| mirrors the agent's pick for this run; `severity` is the value the user |
| (or worker) settled on. |
| - `incident.rootCauseText` / `rootCauseConfidence` / `estimatedImpactText` / |
| `estimatedImpactConfidence` are flattened from the latest successful |
| agent run's `result.rootCause` / `result.estimatedImpact` so the incident |
| row is the single source of truth for "what did we learn". The agent |
| run's raw `result` jsonb is preserved on `agentRun.result` for audit. |
| - `agentRun.result.rootCauseConfidence` is the coarse `"high" | "medium" | "low" | null` |
| rating. `agentRun.result.rootCause` and `agentRun.result.estimatedImpact` |
| are separate objects carrying a free-text `text` plus a numeric `confidence` |
| on a 0-10 scale (10 = backed by verbatim code/log/trace/ticket evidence; |
| 0 = pure speculation). |
| - `agentRun.result.pr` is present when a PR was opened. Mutually-exclusive |
| with the no-PR conclusion fields `agentRun.result.noiseClassification` / |
| `agentRun.result.resolutionClassification`, which are set when the agent |
| decided not to ship a fix (the issue is noise, or already fixed in the |
| current code, or PR policy = never). |
| - `agentRun.result.linearTicket` is present when Linear is connected and a |
| ticket was filed. |
| - `pullRequests` and `linearTickets` mirror the same underlying records but |
| as the persistent state we track (PR state may change after the webhook |
| fires — e.g. a PR opened at agent-run-completion time might be merged |
| later; that mid-flight state is what's in the payload). |
| - The `agentRun.result` shape evolves with the agent runtime. Treat unknown |
| fields as additive. |
|
|
| ## Best practices |
|
|
| - **Respond fast.** Return 2xx within 10 seconds. Do the actual work async. |
| - **De-dupe** on `Superlog-Delivery`. We may retry a delivery you already |
| processed (e.g. your server returned 200 but the connection dropped before we |
| saw it). |
| - **Verify the signature** on every request. Reject if the timestamp drifts |
| more than ~5 minutes from your clock. |
| - **Don't trust the URL host** for routing — anyone with the URL could try to |
| POST to it. The HMAC is your only proof. |
|
|
