Set Up Superlog Webhooks for Incident Events

Superlog sends webhooks to your server when something happens to an incident in a project. They’re designed as messages to relay to an outgoing integration — Telegram, email, SMS, a status page, PagerDuty, your data warehouse, or any internal tooling — so every payload carries both render-ready text and the full structured state.

The model: two events

There are exactly two events, and they map directly onto how a messaging integration thinks:

Event	Fires when	Relay it as
`incident.created`	A new incident is opened.	A new message / a new thread.
`incident.updated`	Anything else happens on that incident (see `change.kind`).	A reply in that thread (or an edit).

Everything that used to be its own event — resolve, reopen, merge, an investigation starting / finishing / failing / asking for input — is now an incident.updated distinguished by a change.kind field. The incident is the “thread”; an agent run (investigation) is just activity on it. change.kind is one of:

`change.kind`	Meaning
`resolved`	The incident closed — manual resolve, PR merged, agent classified already-fixed, autorecovery confirmed, or auto-closed as noise. Adds `change.resolution`.
`reopened`	A resolved/noise-closed incident reopened. Adds `change.reason` (`issue_regressed` \| `manual`) and `change.previousStatus`.
`merged`	The incident was a duplicate and merged into a survivor. Adds `change.mergedInto` and `change.evidence`.
`agent_started`	An investigation started. Adds `agentRun`.
`agent_completed`	An investigation finished with findings — a PR was opened or it reached a no-PR conclusion. Adds `agentRun`, `events`, `pullRequests`, `linearTickets`.
`agent_failed`	An investigation failed. Adds `agentRun` (with `failureReason` / `failureCategory`).
`agent_awaiting_input`	An investigation paused for a human (repo pick, or GitHub not connected). Adds `agentRun` and `change.reason` / `change.summary` / `change.question`.

For the simplest possible integration, subscribe to both events and forward message.title / message.body (see The message object) verbatim. You never have to parse the rest of the schema.

Each endpoint chooses whether it receives incident.created, incident.updated, or both (both by default).

Configuring an endpoint

Open Webhook Settings

Navigate to Settings → Webhooks for the project that should send events.

Add your endpoint URL

Paste your HTTPS endpoint URL (e.g. https://your-app.example.com/hooks/superlog) into the URL field.

Pick the events

Tick the events this endpoint should receive. Both are selected by default.

Save and copy the signing secret

Click Add endpoint. Superlog immediately generates a signing secret prefixed whsec_ and shows it to you once. Copy it to your secrets manager — it is never displayed again.

Verify transport with Send test

Use the Send test button to fire a stub payload to your endpoint. The test delivery appears in the live delivery log under the endpoint so you can confirm the request arrived and your server returned a 2xx.

Expand an endpoint to change its subscribed events later. You can disable, rotate the secret, or delete an endpoint at any time from Settings → Webhooks.

Disable: suspends delivery without deleting history. Re-enable at any time.
Rotate secret: generates a new whsec_ secret immediately. Update your handler before rotating to avoid a gap.
Delete: permanently removes the endpoint and all its delivery history.

The Send test payload has the shape { event, eventId, occurredAt, test: true, message: { title, body }, project } and does not include incident, change, agentRun, events, pullRequests, or linearTickets. Use it to verify transport and signature only.

Delivery semantics

Events are delivered as POST with Content-Type: application/json.
The request timeout is 10 seconds. Any response that takes longer is treated as a failure.
Non-2xx responses, connection errors, and timeouts are all retried with the following backoff schedule:

Attempt	Delay before attempt
1	Immediate
2	30 seconds
3	1 minute
4	2 minutes
5	5 minutes
6	15 minutes
7	1 hour
8	6 hours

After all 8 attempts fail (~8 hours elapsed), the delivery is marked failed and Superlog stops retrying.

Automatic retries reuse the same Superlog-Delivery UUID — use it as your idempotency key.
Manual redeliver from Settings enqueues a brand-new delivery row with a new UUID. If you redeliver something that was already delivered successfully, your receiver will see it twice.
Disabling an endpoint stops new deliveries from being enqueued; any deliveries still pending when 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.

Request headers

Every webhook request includes the following headers:

Header	Value
`Superlog-Signature`	`t=<unix-ts>,v1=<hex>` — HMAC-SHA256 over `<ts>.<body>`
`Superlog-Event`	Event type — `incident.created` or `incident.updated`
`Superlog-Delivery`	UUID of this delivery — stable across retries
`User-Agent`	`Superlog-Webhooks/1.0`

Verifying signatures

Every request is signed with HMAC-SHA256 using the whsec_ secret you saved at endpoint creation. You must verify this signature on every request before processing the payload. The Superlog-Signature header has the format:

Superlog-Signature: t=1715450000,v1=<hex>

The signed string is <t>.<rawRequestBody>. Here is a complete TypeScript verification helper:

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);
}

Always verify against the raw request body before JSON-parsing it. Frameworks that re-serialize JSON (reordering keys, stripping whitespace) will produce a different byte sequence and a different hash, causing every signature check to fail.

Common envelope

Both events share the same top-level shape:

{
  "event": "incident.created",                  // matches the Superlog-Event header
  "eventId": "5f0a6b6e-...",                    // UUID, unique per event (de-dupe key)
  "occurredAt": "2026-05-11T12:34:56.000Z",     // when we built the payload (ISO-8601)
  "project": { "id": "uuid", "name": "Default", "slug": "default" },
  "message": {                                   // render-ready text — forward verbatim if you like
    "title": "TypeError in /api/orders",
    "body": "New incident (SEV-2 · orders · production)."
  },
  "incident": { }                                // see "The incident object" below
}

incident.updated additionally carries a change object (always), and — for agent-related changes — an agentRun object (and, on agent_completed, the events / pullRequests / linearTickets arrays). Treat any unknown top-level keys as additive.

The `message` object

The single most useful field for a relay: a pre-rendered, channel-neutral { title, body } you can forward to Telegram/email/SMS without understanding the rest of the schema. title is the incident title (the “thread subject”); body is a one-line description of what just happened — e.g. "Resolved: looks fine now", "Investigation complete: <summary>. Opened PR: <url>", or "Reopened — the underlying issue regressed." For anything richer, read the structured fields below.

The `incident` object

Present on every event. A curated projection of the incident (Slack anchors, billing cooldowns, and other operational columns are intentionally omitted):

{
  "id": "uuid",
  "title": "TypeError in /api/orders",
  "codename": "squishy-narwhal",
  "status": "open",                              // "open" | "resolved" | "autoresolved_noise" | "merged"
  "severity": "SEV-2",                           // "SEV-1" | "SEV-2" | "SEV-3" | null
  "suggestedSeverity": "SEV-2",
  "service": "orders",
  "environment": "production",                   // nullable
  "firstSeen": "2026-05-11T11:00:00.000Z",
  "lastSeen": "2026-05-11T12:30:00.000Z",
  "issueCount": 14,
  "agentSummary": null,
  "rootCauseText": null,                         // flattened from the latest successful run
  "rootCauseConfidence": null,                   // 0-10
  "estimatedImpactText": null,
  "estimatedImpactConfidence": null,             // 0-10
  "noiseClassification": null,
  "resolutionClassification": null,
  "findingsAgentRunId": null,
  "resolvedAt": null,
  "resolvedByKind": null,                        // e.g. "slack_manual" | "agent_pr_merged" | "agent_classification" | "autorecovery_confirmed"
  "resolvedReasonCode": null,
  "resolvedReasonText": null,
  "mergedIntoId": null,
  "mergedAt": null
}

The `agentRun` object

Present on incident.updated when change.kind is one of the agent_* kinds:

{
  "id": "uuid",
  "state": "running",                            // queued | running | awaiting_human | blocked_no_github | complete | failed | ...
  "runtime": "anthropic",
  "trigger": "incident",                         // incident | pr_comment | feedback | slack_reply | issue_joined
  "startedAt": "2026-05-11T12:20:00.000Z",
  "completedAt": null,
  "cumulativeRuntimeMinutes": 3,
  "resumeCount": 0,
  "failureReason": null,                         // set when change.kind = "agent_failed"
  "failureCategory": null,                       // "agent" | "deliverable" | "infra" (derived from failureReason)
  "selectedRepoFullName": null,
  "selectedBaseBranch": null,
  "result": null                                 // the agent's AgentRunResult (rich on agent_completed)
}

`incident.created`

Just the common envelope — { event, eventId, occurredAt, project, message, incident } with incident.status = "open". Relay it as a new message / open a new thread keyed on incident.id.

`incident.updated`

The common envelope plus a change object. change.kind tells you what happened; switch on it to decide how to render the reply. Some kinds add fields to change; agent kinds add an agentRun (and agent_completed adds the events / pullRequests / linearTickets arrays).

`change.kind = "resolved"`

Fires for every path that closes an incident, including auto-close as noise.

{
  "change": {
    "kind": "resolved",
    "resolution": {
      "kind": "slack_manual",                    // resolvedByKind; "autoresolved_noise" for the noise path
      "reasonCode": "manual",
      "reasonText": "looks fine now",
      "resolvedAt": "2026-05-11T13:00:00.000Z",
      "status": "resolved"                       // "resolved" | "autoresolved_noise"
    }
  }
}

Use change.resolution.status to tell a real resolve ("resolved") from a noise auto-close ("autoresolved_noise"). On the noise path, resolution.kind / reasonCode / resolvedAt are filled from the incident’s noise-close metadata.

`change.kind = "reopened"`

{
  "change": {
    "kind": "reopened",
    "reason": "issue_regressed",                 // "issue_regressed" | "manual"
    "previousStatus": "resolved"                 // status before reopen, may be null
  }
}

`change.kind = "merged"`

The incident is the source (now status: "merged"); change.mergedInto is the survivor it folded into.

{
  "change": {
    "kind": "merged",
    "mergedInto": {
      "id": "uuid",
      "codename": "brave-otter",
      "title": "Other incident title",
      "status": "open"
    },
    "evidence": "Same stack frame and root cause as the survivor."
  }
}

`change.kind = "agent_started"`

change is just { "kind": "agent_started" }; the payload adds agentRun (state running, result: null).

`change.kind = "agent_failed"`

change is just { "kind": "agent_failed" }; the payload adds agentRun with state: "failed", failureReason set, and failureCategory derived from it.

`change.kind = "agent_awaiting_input"`

{
  "change": {
    "kind": "agent_awaiting_input",
    "reason": "repository_selection",            // "repository_selection" | "no_github_install" | "no_accessible_repos"
    "summary": "I need to know which repo to investigate.",
    "question": "orders or web?"                  // may be null (e.g. GitHub-blocked)
  }
}

`change.kind = "agent_completed"`

The richest update — see the full example below.

`agent_completed` payload (full example)

When change.kind = "agent_completed", the incident.updated payload — in addition to agentRun — embeds the run’s chronological events, opened pullRequests, and filed linearTickets.

{
  "event": "incident.updated",
  "eventId": "5f0a6b6e-...",
  "occurredAt": "2026-05-11T12:34:56.000Z",
  "project": { "id": "uuid", "name": "Default", "slug": "default" },
  "message": {
    "title": "TypeError in /api/orders",
    "body": "Investigation complete: Root cause: missing null check in orders.ts:42 Opened PR: https://github.com/acme/orders/pull/4271"
  },
  "change": { "kind": "agent_completed" },
  "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

The incident and agentRun objects follow the shared shapes in Common envelope above (that’s the source of truth); the example shows representative values, and its incident block is abbreviated relative to the full field list.
agentRun.state is always "complete" for this change. A failed run sends change.kind = "agent_failed"; a run whose incident was merged into another sends change.kind = "merged" instead.
agentRun.failureReason is always null here for the same reason.
incident.status is one of "open" | "resolved" | "autoresolved_noise" | "merged". Note that agent_completed can fire while the incident is still "open" — the run finished, but no one has resolved the incident yet.
incident.severity and agentRun.result.severity are "SEV-1" | "SEV-2" | "SEV-3" | null. incident.suggestedSeverity mirrors the agent’s pick for this run; incident.severity is the value a user or automated worker settled on.
incident.rootCauseText / rootCauseConfidence / estimatedImpactText / estimatedImpactConfidence are flattened from the latest successful run’s result.rootCause / result.estimatedImpact so the incident row is the single source of truth for “what did we learn”. The run’s raw result jsonb is preserved on agentRun.result for audit.
agentRun.result.rootCauseConfidence is a coarse "high" | "medium" | "low" | null rating. agentRun.result.rootCause and agentRun.result.estimatedImpact each carry a free-text text plus a numeric confidence on a 0–10 scale (10 = backed by verbatim code/log/trace/ticket evidence; 0 = speculation).
agentRun.result.pr is present when a fix PR was opened. It is mutually exclusive with agentRun.result.noiseClassification and agentRun.result.resolutionClassification, which are set when the agent decided not to ship a fix (the issue is noise, already fixed in current code, or PR policy = never).
agentRun.result.linearTicket is present when Linear is connected and a ticket was filed.
pullRequests and linearTickets reflect the persistent state Superlog tracks at the moment the webhook fires. A PR that was "open" at dispatch time may be merged or closed later — Superlog does not send a second event when that happens.
Treat unknown fields in agentRun.result as additive. The agent result shape evolves over time.

Best practices

Following these practices protects your integration against retries, replay attacks, and spoofed requests.

Route on event, then change.kind. incident.created → start a new thread keyed on incident.id; incident.updated → look up that thread and post a reply (or edit), branching on change.kind. For the simplest integration, just forward message.title / message.body and ignore the rest.
Respond fast. Return a 2xx within 10 seconds and do the real work asynchronously. Slow handlers cause retries that your de-duplication logic must handle.
De-duplicate on Superlog-Delivery. Superlog may retry a delivery your server already processed — for example, if your server returned 200 but the connection dropped before Superlog saw it. Store the delivery UUID on receipt and skip processing if you have seen it before.
Verify the signature on every request. Reject requests where the timestamp drifts more than 5 minutes from your clock. This protects against replay attacks using captured payloads.
Don’t rely on the URL for authenticity. Anyone who discovers your webhook URL could POST to it. The HMAC signature is your only cryptographic proof that the payload came from Superlog.

Get Started

Core Concepts

Integrations

Features

Configuration

Set Up Superlog Webhooks for Incident Events

The model: two events

Configuring an endpoint

Delivery semantics

Request headers

Verifying signatures

Common envelope

The `message` object

The `incident` object

The `agentRun` object

`incident.created`

`incident.updated`

`change.kind = "resolved"`

`change.kind = "reopened"`

`change.kind = "merged"`

`change.kind = "agent_started"`

`change.kind = "agent_failed"`

`change.kind = "agent_awaiting_input"`

`change.kind = "agent_completed"`

`agent_completed` payload (full example)

Field notes

Best practices

​The model: two events

​Configuring an endpoint

​Delivery semantics

​Request headers

​Verifying signatures

​Common envelope

​The message object

​The incident object

​The agentRun object

​incident.created

​incident.updated

​change.kind = "resolved"

​change.kind = "reopened"

​change.kind = "merged"

​change.kind = "agent_started"

​change.kind = "agent_failed"

​change.kind = "agent_awaiting_input"

​change.kind = "agent_completed"

​agent_completed payload (full example)

​Field notes

​Best practices

The model: two events

Configuring an endpoint

Delivery semantics

Request headers

Verifying signatures

Common envelope

The `message` object

The `incident` object

The `agentRun` object

`incident.created`

`incident.updated`

`change.kind = "resolved"`

`change.kind = "reopened"`

`change.kind = "merged"`

`change.kind = "agent_started"`

`change.kind = "agent_failed"`

`change.kind = "agent_awaiting_input"`

`change.kind = "agent_completed"`

`agent_completed` payload (full example)

Field notes

Best practices